diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index f7780503be..4f624151f1 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -24,6 +24,8 @@ Thanks, you're awesome :-) --> #### Improvements +* Expanded field set definitions for `source.*` and `destination.*`. #967 + #### Deprecated ### Tooling and Artifact Changes diff --git a/code/go/ecs/destination.go b/code/go/ecs/destination.go index b283ec3b2f..e3417e5bb9 100644 --- a/code/go/ecs/destination.go +++ b/code/go/ecs/destination.go @@ -19,8 +19,15 @@ package ecs -// Destination fields describe details about the destination of a packet/event. +// Destination fields capture details about the receiver of a network +// exchange/packet. These fields are populated from a network event, packet, or +// other event containing details of a network transaction. // Destination fields are usually populated in conjunction with source fields. +// The source and destination fields are considered the baseline and should +// always be filled if an event contains source and destination details from a +// network transaction. If the event also contains identification of the client +// and server roles, then the client and server fields should also be +// populated. type Destination struct { // Some event destination addresses are defined ambiguously. The event will // sometimes list an IP, a domain or a unix socket. You should always diff --git a/code/go/ecs/source.go b/code/go/ecs/source.go index 8fe352bc72..f8ab84d581 100644 --- a/code/go/ecs/source.go +++ b/code/go/ecs/source.go @@ -19,8 +19,15 @@ package ecs -// Source fields describe details about the source of a packet/event. +// Source fields capture details about the sender of a network exchange/packet. +// These fields are populated from a network event, packet, or other event +// containing details of a network transaction. // Source fields are usually populated in conjunction with destination fields. +// The source and destination fields are considered the baseline and should +// always be filled if an event contains source and destination details from a +// network transaction. If the event also contains identification of the client +// and server roles, then the client and server fields should also be +// populated. type Source struct { // Some event source addresses are defined ambiguously. The event will // sometimes list an IP, a domain or a unix socket. You should always diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index b39f2c2949..da97a3c5f8 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -803,9 +803,9 @@ example: `docker` [[ecs-destination]] === Destination Fields -Destination fields describe details about the destination of a packet/event. +Destination fields capture details about the receiver of a network exchange/packet. These fields are populated from a network event, packet, or other event containing details of a network transaction. -Destination fields are usually populated in conjunction with source fields. +Destination fields are usually populated in conjunction with source fields. The source and destination fields are considered the baseline and should always be filled if an event contains source and destination details from a network transaction. If the event also contains identification of the client and server roles, then the client and server fields should also be populated. ==== Destination Field Details @@ -5185,9 +5185,9 @@ example: `3.2.4` [[ecs-source]] === Source Fields -Source fields describe details about the source of a packet/event. +Source fields capture details about the sender of a network exchange/packet. These fields are populated from a network event, packet, or other event containing details of a network transaction. -Source fields are usually populated in conjunction with destination fields. +Source fields are usually populated in conjunction with destination fields. The source and destination fields are considered the baseline and should always be filled if an event contains source and destination details from a network transaction. If the event also contains identification of the client and server roles, then the client and server fields should also be populated. ==== Source Field Details diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index 782d1fdd50..c632daaead 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -562,9 +562,15 @@ - name: destination title: Destination group: 2 - description: 'Destination fields describe details about the destination of a packet/event. - - Destination fields are usually populated in conjunction with source fields.' + description: 'Destination fields capture details about the receiver of a network + exchange/packet. These fields are populated from a network event, packet, or + other event containing details of a network transaction. + + Destination fields are usually populated in conjunction with source fields. + The source and destination fields are considered the baseline and should always + be filled if an event contains source and destination details from a network + transaction. If the event also contains identification of the client and server + roles, then the client and server fields should also be populated.' type: group fields: - name: address @@ -4286,9 +4292,15 @@ - name: source title: Source group: 2 - description: 'Source fields describe details about the source of a packet/event. - - Source fields are usually populated in conjunction with destination fields.' + description: 'Source fields capture details about the sender of a network exchange/packet. + These fields are populated from a network event, packet, or other event containing + details of a network transaction. + + Source fields are usually populated in conjunction with destination fields. + The source and destination fields are considered the baseline and should always + be filled if an event contains source and destination details from a network + transaction. If the event also contains identification of the client and server + roles, then the client and server fields should also be populated.' type: group fields: - name: address diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 8ed5b86a80..490b00eb74 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -957,9 +957,15 @@ container: title: Container type: group destination: - description: 'Destination fields describe details about the destination of a packet/event. - - Destination fields are usually populated in conjunction with source fields.' + description: 'Destination fields capture details about the receiver of a network + exchange/packet. These fields are populated from a network event, packet, or other + event containing details of a network transaction. + + Destination fields are usually populated in conjunction with source fields. The + source and destination fields are considered the baseline and should always be + filled if an event contains source and destination details from a network transaction. + If the event also contains identification of the client and server roles, then + the client and server fields should also be populated.' fields: destination.address: dashed_name: destination-address @@ -7570,9 +7576,15 @@ service: title: Service type: group source: - description: 'Source fields describe details about the source of a packet/event. - - Source fields are usually populated in conjunction with destination fields.' + description: 'Source fields capture details about the sender of a network exchange/packet. + These fields are populated from a network event, packet, or other event containing + details of a network transaction. + + Source fields are usually populated in conjunction with destination fields. The + source and destination fields are considered the baseline and should always be + filled if an event contains source and destination details from a network transaction. + If the event also contains identification of the client and server roles, then + the client and server fields should also be populated.' fields: source.address: dashed_name: source-address diff --git a/schemas/destination.yml b/schemas/destination.yml index 2400f3745e..42d3e154d5 100644 --- a/schemas/destination.yml +++ b/schemas/destination.yml @@ -4,9 +4,13 @@ group: 2 short: Fields about the destination side of a network connection, used with source. description: > - Destination fields describe details about the destination of a packet/event. + Destination fields capture details about the receiver of a network exchange/packet. These fields are populated from + a network event, packet, or other event containing details of a network transaction. - Destination fields are usually populated in conjunction with source fields. + Destination fields are usually populated in conjunction with source fields. The source and destination + fields are considered the baseline and should always be filled if an event contains source + and destination details from a network transaction. If the event also contains identification of the + client and server roles, then the client and server fields should also be populated. type: group fields: diff --git a/schemas/source.yml b/schemas/source.yml index 05379a48c3..65539b3d60 100644 --- a/schemas/source.yml +++ b/schemas/source.yml @@ -4,9 +4,13 @@ group: 2 short: Fields about the source side of a network connection, used with destination. description: > - Source fields describe details about the source of a packet/event. + Source fields capture details about the sender of a network exchange/packet. These fields are populated from + a network event, packet, or other event containing details of a network transaction. - Source fields are usually populated in conjunction with destination fields. + Source fields are usually populated in conjunction with destination fields. The source and destination + fields are considered the baseline and should always be filled if an event contains source + and destination details from a network transaction. If the event also contains identification of the + client and server roles, then the client and server fields should also be populated. type: group fields: