From c84e5a7d277cce68fb9102580a6fef92be5ad432 Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Tue, 30 Nov 2021 09:47:01 -0600 Subject: [PATCH] Expand `[source|destination|client|server].domain` field descriptions (#1673) * improve .domain description and add example value * Update field-details.asciidoc fix typos * typo fix * word ordering * use correct quantifier Co-authored-by: djptek --- docs/field-details.asciidoc | 24 +++++++++----- experimental/generated/beats/fields.ecs.yml | 28 +++++++++++++--- experimental/generated/csv/fields.csv | 8 ++--- experimental/generated/ecs/ecs_flat.yml | 32 +++++++++++++----- experimental/generated/ecs/ecs_nested.yml | 36 ++++++++++++++++----- generated/beats/fields.ecs.yml | 28 +++++++++++++--- generated/csv/fields.csv | 8 ++--- generated/ecs/ecs_flat.yml | 32 +++++++++++++----- generated/ecs/ecs_nested.yml | 36 ++++++++++++++++----- schemas/client.yml | 12 +++++++ schemas/destination.yml | 8 ++++- schemas/server.yml | 8 ++++- schemas/source.yml | 8 ++++- 13 files changed, 209 insertions(+), 59 deletions(-) diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index d4e513c8f3..489daae182 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -353,13 +353,15 @@ example: `184` [[field-client-domain]] <> -| Client domain. +| The domain name of the client system. -type: keyword +This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. +type: keyword +example: `foo.example.com` | core @@ -1264,13 +1266,15 @@ example: `184` [[field-destination-domain]] <> -| Destination domain. +| The domain name of the destination system. -type: keyword +This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. +type: keyword +example: `foo.example.com` | core @@ -7185,13 +7189,15 @@ example: `184` [[field-server-domain]] <> -| Server domain. +| The domain name of the server system. -type: keyword +This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. +type: keyword +example: `foo.example.com` | core @@ -7689,13 +7695,15 @@ example: `184` [[field-source-domain]] <> -| Source domain. +| The domain name of the source system. -type: keyword +This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. +type: keyword +example: `foo.example.com` | core diff --git a/experimental/generated/beats/fields.ecs.yml b/experimental/generated/beats/fields.ecs.yml index 0bff88a49d..58f2c421db 100644 --- a/experimental/generated/beats/fields.ecs.yml +++ b/experimental/generated/beats/fields.ecs.yml @@ -253,7 +253,12 @@ level: core type: keyword ignore_above: 1024 - description: Client domain. + description: 'The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword @@ -1037,7 +1042,12 @@ level: core type: keyword ignore_above: 1024 - description: Destination domain. + description: 'The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword @@ -5807,7 +5817,12 @@ level: core type: keyword ignore_above: 1024 - description: Server domain. + description: 'The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword @@ -6415,7 +6430,12 @@ level: core type: keyword ignore_above: 1024 - description: Source domain. + description: 'The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword diff --git a/experimental/generated/csv/fields.csv b/experimental/generated/csv/fields.csv index 190732df9f..1e93acd770 100644 --- a/experimental/generated/csv/fields.csv +++ b/experimental/generated/csv/fields.csv @@ -21,7 +21,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev+exp,true,client,client.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,client,client.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,client,client.bytes,long,core,,184,Bytes sent from the client to the server. -8.1.0-dev+exp,true,client,client.domain,keyword,core,,,Client domain. +8.1.0-dev+exp,true,client,client.domain,keyword,core,,foo.example.com,The domain name of the client. 8.1.0-dev+exp,true,client,client.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev+exp,true,client,client.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev+exp,true,client,client.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -107,7 +107,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev+exp,true,destination,destination.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,destination,destination.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,destination,destination.bytes,long,core,,184,Bytes sent from the destination to the source. -8.1.0-dev+exp,true,destination,destination.domain,keyword,core,,,Destination domain. +8.1.0-dev+exp,true,destination,destination.domain,keyword,core,,foo.example.com,The domain name of the destination. 8.1.0-dev+exp,true,destination,destination.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev+exp,true,destination,destination.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev+exp,true,destination,destination.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -657,7 +657,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev+exp,true,server,server.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,server,server.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,server,server.bytes,long,core,,184,Bytes sent from the server to the client. -8.1.0-dev+exp,true,server,server.domain,keyword,core,,,Server domain. +8.1.0-dev+exp,true,server,server.domain,keyword,core,,foo.example.com,The domain name of the server. 8.1.0-dev+exp,true,server,server.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev+exp,true,server,server.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev+exp,true,server,server.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -722,7 +722,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev+exp,true,source,source.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,source,source.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev+exp,true,source,source.bytes,long,core,,184,Bytes sent from the source to the destination. -8.1.0-dev+exp,true,source,source.domain,keyword,core,,,Source domain. +8.1.0-dev+exp,true,source,source.domain,keyword,core,,foo.example.com,The domain name of the source. 8.1.0-dev+exp,true,source,source.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev+exp,true,source,source.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev+exp,true,source,source.geo.continent_name,keyword,core,,North America,Name of the continent. diff --git a/experimental/generated/ecs/ecs_flat.yml b/experimental/generated/ecs/ecs_flat.yml index 8987db7e25..89be366bca 100644 --- a/experimental/generated/ecs/ecs_flat.yml +++ b/experimental/generated/ecs/ecs_flat.yml @@ -226,13 +226,17 @@ client.bytes: type: long client.domain: dashed_name: client-domain - description: Client domain. + description: 'The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: client.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Client domain. + short: The domain name of the client. type: keyword client.geo.city_name: dashed_name: client-geo-city-name @@ -1279,13 +1283,17 @@ destination.bytes: type: long destination.domain: dashed_name: destination-domain - description: Destination domain. + description: 'The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: destination.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Destination domain. + short: The domain name of the destination. type: keyword destination.geo.city_name: dashed_name: destination-geo-city-name @@ -8337,13 +8345,17 @@ server.bytes: type: long server.domain: dashed_name: server-domain - description: Server domain. + description: 'The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: server.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Server domain. + short: The domain name of the server. type: keyword server.geo.city_name: dashed_name: server-geo-city-name @@ -9237,13 +9249,17 @@ source.bytes: type: long source.domain: dashed_name: source-domain - description: Source domain. + description: 'The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: source.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Source domain. + short: The domain name of the source. type: keyword source.geo.city_name: dashed_name: source-geo-city-name diff --git a/experimental/generated/ecs/ecs_nested.yml b/experimental/generated/ecs/ecs_nested.yml index bd9e1a2bf2..5374953dd7 100644 --- a/experimental/generated/ecs/ecs_nested.yml +++ b/experimental/generated/ecs/ecs_nested.yml @@ -388,13 +388,18 @@ client: type: long client.domain: dashed_name: client-domain - description: Client domain. + description: 'The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: client.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Client domain. + short: The domain name of the client. type: keyword client.geo.city_name: dashed_name: client-geo-city-name @@ -1699,13 +1704,18 @@ destination: type: long destination.domain: dashed_name: destination-domain - description: Destination domain. + description: 'The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: destination.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Destination domain. + short: The domain name of the destination. type: keyword destination.geo.city_name: dashed_name: destination-geo-city-name @@ -10073,13 +10083,18 @@ server: type: long server.domain: dashed_name: server-domain - description: Server domain. + description: 'The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: server.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Server domain. + short: The domain name of the server. type: keyword server.geo.city_name: dashed_name: server-geo-city-name @@ -11057,13 +11072,18 @@ source: type: long source.domain: dashed_name: source-domain - description: Source domain. + description: 'The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: source.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Source domain. + short: The domain name of the source. type: keyword source.geo.city_name: dashed_name: source-geo-city-name diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index 4acd04f9aa..df3e7dd636 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -203,7 +203,12 @@ level: core type: keyword ignore_above: 1024 - description: Client domain. + description: 'The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword @@ -949,7 +954,12 @@ level: core type: keyword ignore_above: 1024 - description: Destination domain. + description: 'The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword @@ -5548,7 +5558,12 @@ level: core type: keyword ignore_above: 1024 - description: Server domain. + description: 'The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword @@ -6156,7 +6171,12 @@ level: core type: keyword ignore_above: 1024 - description: Source domain. + description: 'The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com - name: geo.city_name level: core type: keyword diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv index a87a150e08..da8d6a79a6 100644 --- a/generated/csv/fields.csv +++ b/generated/csv/fields.csv @@ -14,7 +14,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev,true,client,client.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev,true,client,client.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev,true,client,client.bytes,long,core,,184,Bytes sent from the client to the server. -8.1.0-dev,true,client,client.domain,keyword,core,,,Client domain. +8.1.0-dev,true,client,client.domain,keyword,core,,foo.example.com,The domain name of the client. 8.1.0-dev,true,client,client.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev,true,client,client.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev,true,client,client.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -94,7 +94,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev,true,destination,destination.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev,true,destination,destination.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev,true,destination,destination.bytes,long,core,,184,Bytes sent from the destination to the source. -8.1.0-dev,true,destination,destination.domain,keyword,core,,,Destination domain. +8.1.0-dev,true,destination,destination.domain,keyword,core,,foo.example.com,The domain name of the destination. 8.1.0-dev,true,destination,destination.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev,true,destination,destination.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev,true,destination,destination.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -622,7 +622,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev,true,server,server.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev,true,server,server.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev,true,server,server.bytes,long,core,,184,Bytes sent from the server to the client. -8.1.0-dev,true,server,server.domain,keyword,core,,,Server domain. +8.1.0-dev,true,server,server.domain,keyword,core,,foo.example.com,The domain name of the server. 8.1.0-dev,true,server,server.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev,true,server,server.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev,true,server,server.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -687,7 +687,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.1.0-dev,true,source,source.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.1.0-dev,true,source,source.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.1.0-dev,true,source,source.bytes,long,core,,184,Bytes sent from the source to the destination. -8.1.0-dev,true,source,source.domain,keyword,core,,,Source domain. +8.1.0-dev,true,source,source.domain,keyword,core,,foo.example.com,The domain name of the source. 8.1.0-dev,true,source,source.geo.city_name,keyword,core,,Montreal,City name. 8.1.0-dev,true,source,source.geo.continent_code,keyword,core,,NA,Continent code. 8.1.0-dev,true,source,source.geo.continent_name,keyword,core,,North America,Name of the continent. diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml index 4f2209feaa..70434552bd 100644 --- a/generated/ecs/ecs_flat.yml +++ b/generated/ecs/ecs_flat.yml @@ -157,13 +157,17 @@ client.bytes: type: long client.domain: dashed_name: client-domain - description: Client domain. + description: 'The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: client.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Client domain. + short: The domain name of the client. type: keyword client.geo.city_name: dashed_name: client-geo-city-name @@ -1148,13 +1152,17 @@ destination.bytes: type: long destination.domain: dashed_name: destination-domain - description: Destination domain. + description: 'The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: destination.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Destination domain. + short: The domain name of the destination. type: keyword destination.geo.city_name: dashed_name: destination-geo-city-name @@ -7960,13 +7968,17 @@ server.bytes: type: long server.domain: dashed_name: server-domain - description: Server domain. + description: 'The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: server.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Server domain. + short: The domain name of the server. type: keyword server.geo.city_name: dashed_name: server-geo-city-name @@ -8860,13 +8872,17 @@ source.bytes: type: long source.domain: dashed_name: source-domain - description: Source domain. + description: 'The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from enrichment.' + example: foo.example.com flat_name: source.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Source domain. + short: The domain name of the source. type: keyword source.geo.city_name: dashed_name: source-geo-city-name diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 06247b1d78..0c2da250fa 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -308,13 +308,18 @@ client: type: long client.domain: dashed_name: client-domain - description: Client domain. + description: 'The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: client.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Client domain. + short: The domain name of the client. type: keyword client.geo.city_name: dashed_name: client-geo-city-name @@ -1557,13 +1562,18 @@ destination: type: long destination.domain: dashed_name: destination-domain - description: Destination domain. + description: 'The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: destination.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Destination domain. + short: The domain name of the destination. type: keyword destination.geo.city_name: dashed_name: destination-geo-city-name @@ -9670,13 +9680,18 @@ server: type: long server.domain: dashed_name: server-domain - description: Server domain. + description: 'The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: server.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Server domain. + short: The domain name of the server. type: keyword server.geo.city_name: dashed_name: server-geo-city-name @@ -10654,13 +10669,18 @@ source: type: long source.domain: dashed_name: source-domain - description: Source domain. + description: 'The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another host + naming format. The value may derive from the original event or be added from + enrichment.' + example: foo.example.com flat_name: source.domain ignore_above: 1024 level: core name: domain normalize: [] - short: Source domain. + short: The domain name of the source. type: keyword source.geo.city_name: dashed_name: source-geo-city-name diff --git a/schemas/client.yml b/schemas/client.yml index 539a7a2e18..f7492c96df 100644 --- a/schemas/client.yml +++ b/schemas/client.yml @@ -80,6 +80,18 @@ description: > Client domain. + - name: domain + level: core + type: keyword + short: The domain name of the client. + example: foo.example.com + description: > + The domain name of the client system. + + This value may be a host name, a fully qualified domain name, or another + host naming format. The value may derive from the original event or be + added from enrichment. + - name: registered_domain level: extended type: keyword diff --git a/schemas/destination.yml b/schemas/destination.yml index 6b084e6bab..470a97eb50 100644 --- a/schemas/destination.yml +++ b/schemas/destination.yml @@ -72,8 +72,14 @@ - name: domain level: core type: keyword + short: The domain name of the destination. + example: foo.example.com description: > - Destination domain. + The domain name of the destination system. + + This value may be a host name, a fully qualified domain name, or another + host naming format. The value may derive from the original event or be + added from enrichment. - name: registered_domain level: extended diff --git a/schemas/server.yml b/schemas/server.yml index 1552a42964..58020b4fcd 100644 --- a/schemas/server.yml +++ b/schemas/server.yml @@ -77,8 +77,14 @@ - name: domain level: core type: keyword + short: The domain name of the server. + example: foo.example.com description: > - Server domain. + The domain name of the server system. + + This value may be a host name, a fully qualified domain name, or another + host naming format. The value may derive from the original event or be + added from enrichment. - name: registered_domain level: extended diff --git a/schemas/source.yml b/schemas/source.yml index 644fddcb82..1b3c5a232e 100644 --- a/schemas/source.yml +++ b/schemas/source.yml @@ -72,8 +72,14 @@ - name: domain level: core type: keyword + short: The domain name of the source. + example: foo.example.com description: > - Source domain. + The domain name of the source system. + + This value may be a host name, a fully qualified domain name, or another + host naming format. The value may derive from the original event or be + added from enrichment. - name: registered_domain level: extended