From 16821527e6ca89811101790655dfce810405e2bf 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 # Conflicts: # experimental/generated/csv/fields.csv # generated/csv/fields.csv --- 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 1e4147b21f..1b8a2c0b34 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 b990ba6f2d..1f8b118292 100644 --- a/experimental/generated/beats/fields.ecs.yml +++ b/experimental/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 @@ -987,7 +992,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 @@ -8197,7 +8207,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 @@ -8804,7 +8819,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 9d2b8195e8..0414a1667a 100644 --- a/experimental/generated/csv/fields.csv +++ b/experimental/generated/csv/fields.csv @@ -14,7 +14,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.0.0-dev+exp,true,client,client.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,client,client.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,client,client.bytes,long,core,,184,Bytes sent from the client to the server. -8.0.0-dev+exp,true,client,client.domain,keyword,core,,,Client domain. +8.0.0-dev+exp,true,client,client.domain,keyword,core,,foo.example.com,The domain name of the client. 8.0.0-dev+exp,true,client,client.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev+exp,true,client,client.geo.continent_code,keyword,core,,NA,Continent code. 8.0.0-dev+exp,true,client,client.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -100,7 +100,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.0.0-dev+exp,true,destination,destination.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,destination,destination.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,destination,destination.bytes,long,core,,184,Bytes sent from the destination to the source. -8.0.0-dev+exp,true,destination,destination.domain,keyword,core,,,Destination domain. +8.0.0-dev+exp,true,destination,destination.domain,keyword,core,,foo.example.com,The domain name of the destination. 8.0.0-dev+exp,true,destination,destination.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev+exp,true,destination,destination.geo.continent_code,keyword,core,,NA,Continent code. 8.0.0-dev+exp,true,destination,destination.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -978,7 +978,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.0.0-dev+exp,true,server,server.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,server,server.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,server,server.bytes,long,core,,184,Bytes sent from the server to the client. -8.0.0-dev+exp,true,server,server.domain,keyword,core,,,Server domain. +8.0.0-dev+exp,true,server,server.domain,keyword,core,,foo.example.com,The domain name of the server. 8.0.0-dev+exp,true,server,server.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev+exp,true,server,server.geo.continent_code,keyword,core,,NA,Continent code. 8.0.0-dev+exp,true,server,server.geo.continent_name,keyword,core,,North America,Name of the continent. @@ -1043,7 +1043,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 8.0.0-dev+exp,true,source,source.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,source,source.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev+exp,true,source,source.bytes,long,core,,184,Bytes sent from the source to the destination. -8.0.0-dev+exp,true,source,source.domain,keyword,core,,,Source domain. +8.0.0-dev+exp,true,source,source.domain,keyword,core,,foo.example.com,The domain name of the source. 8.0.0-dev+exp,true,source,source.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev+exp,true,source,source.geo.continent_code,keyword,core,,NA,Continent code. 8.0.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 33d8f8c6ee..27d630946c 100644 --- a/experimental/generated/ecs/ecs_flat.yml +++ b/experimental/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 @@ -1210,13 +1214,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 @@ -12148,13 +12156,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 @@ -13048,13 +13060,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 67e183c119..b5aade9f2f 100644 --- a/experimental/generated/ecs/ecs_nested.yml +++ b/experimental/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 @@ -1619,13 +1624,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 @@ -14234,13 +14244,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 @@ -15218,13 +15233,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 3baea15448..71eef281ee 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 @@ -6155,7 +6170,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 fe1b1711c6..b49e6f8305 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.0.0-dev,true,client,client.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev,true,client,client.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev,true,client,client.bytes,long,core,,184,Bytes sent from the client to the server. -8.0.0-dev,true,client,client.domain,keyword,core,,,Client domain. +8.0.0-dev,true,client,client.domain,keyword,core,,foo.example.com,The domain name of the client. 8.0.0-dev,true,client,client.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev,true,client,client.geo.continent_code,keyword,core,,NA,Continent code. 8.0.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.0.0-dev,true,destination,destination.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev,true,destination,destination.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev,true,destination,destination.bytes,long,core,,184,Bytes sent from the destination to the source. -8.0.0-dev,true,destination,destination.domain,keyword,core,,,Destination domain. +8.0.0-dev,true,destination,destination.domain,keyword,core,,foo.example.com,The domain name of the destination. 8.0.0-dev,true,destination,destination.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev,true,destination,destination.geo.continent_code,keyword,core,,NA,Continent code. 8.0.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.0.0-dev,true,server,server.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev,true,server,server.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev,true,server,server.bytes,long,core,,184,Bytes sent from the server to the client. -8.0.0-dev,true,server,server.domain,keyword,core,,,Server domain. +8.0.0-dev,true,server,server.domain,keyword,core,,foo.example.com,The domain name of the server. 8.0.0-dev,true,server,server.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev,true,server,server.geo.continent_code,keyword,core,,NA,Continent code. 8.0.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.0.0-dev,true,source,source.as.organization.name,keyword,extended,,Google LLC,Organization name. 8.0.0-dev,true,source,source.as.organization.name.text,match_only_text,extended,,Google LLC,Organization name. 8.0.0-dev,true,source,source.bytes,long,core,,184,Bytes sent from the source to the destination. -8.0.0-dev,true,source,source.domain,keyword,core,,,Source domain. +8.0.0-dev,true,source,source.domain,keyword,core,,foo.example.com,The domain name of the source. 8.0.0-dev,true,source,source.geo.city_name,keyword,core,,Montreal,City name. 8.0.0-dev,true,source,source.geo.continent_code,keyword,core,,NA,Continent code. 8.0.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 dacd494ef6..6ff21d7b78 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 5f752c1cf9..7d2ff559d5 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 3011c97b46..368a4c8ab9 100644 --- a/schemas/client.yml +++ b/schemas/client.yml @@ -64,6 +64,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 c600377b92..6e95aeebaf 100644 --- a/schemas/destination.yml +++ b/schemas/destination.yml @@ -56,8 +56,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 b5d66c63e7..7ee3648519 100644 --- a/schemas/server.yml +++ b/schemas/server.yml @@ -61,8 +61,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 8f3e5f1350..5d8ecbc773 100644 --- a/schemas/source.yml +++ b/schemas/source.yml @@ -56,8 +56,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