From 488798bf111fc9719ef18f64db690280ec6cc031 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Thu, 12 Nov 2020 16:32:20 -0500 Subject: [PATCH] Clarify x509 definition guidance for network events with only one cert (#1114) --- CHANGELOG.md | 2 ++ code/go/ecs/x509.go | 13 +++++++------ docs/field-details.asciidoc | 6 +++++- experimental/generated/beats/fields.ecs.yml | 17 ++++++++++------- experimental/generated/ecs/ecs_nested.yml | 16 +++++++++------- generated/beats/fields.ecs.yml | 17 ++++++++++------- generated/ecs/ecs_nested.yml | 16 +++++++++------- schemas/x509.yml | 10 ++++++---- 8 files changed, 58 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a1927875df..f5842b1e10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,8 @@ All notable changes to this project will be documented in this file based on the * Provided better guidance for mapping network events. #969 * Added the field `.subdomain` under `client`, `destination`, `server`, `source` and `url`, to match its presence at `dns.question.subdomain`. #981 +* Clarified ambiguity in guidance on how to use x509 fields for connections with + only one certificate. #1114 ### Tooling and Artifact Changes diff --git a/code/go/ecs/x509.go b/code/go/ecs/x509.go index 99d916a641..d3509dda98 100644 --- a/code/go/ecs/x509.go +++ b/code/go/ecs/x509.go @@ -26,12 +26,13 @@ import ( // This implements the common core fields for x509 certificates. This // information is likely logged with TLS sessions, digital signatures found in // executable binaries, S/MIME information in email bodies, or analysis of -// files on disk. When only a single certificate is logged in an event, it -// should be nested under `file`. When hashes of the DER-encoded certificate -// are available, the `hash` data set should be populated as well (e.g. -// `file.hash.sha256`). For events that contain certificate information for -// both sides of the connection, the x509 object could be nested under the -// respective side of the connection information (e.g. `tls.server.x509`). +// files on disk. +// When the certificate relates to a file, use the fields at `file.x509`. When +// hashes of the DER-encoded certificate are available, the `hash` data set +// should be populated as well (e.g. `file.hash.sha256`). +// Events that contain certificate information about network connections, +// should use the x509 fields under the relevant TLS fields: `tls.server.x509` +// and/or `tls.client.x509`. type X509 struct { // Version of x509 format. VersionNumber string `ecs:"version_number"` diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index f961b6fa89..d728ba703a 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -6957,7 +6957,11 @@ example: `Critical` [[ecs-x509]] === x509 Certificate Fields -This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files on disk. When only a single certificate is logged in an event, it should be nested under `file`. When hashes of the DER-encoded certificate are available, the `hash` data set should be populated as well (e.g. `file.hash.sha256`). For events that contain certificate information for both sides of the connection, the x509 object could be nested under the respective side of the connection information (e.g. `tls.server.x509`). +This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files on disk. + +When the certificate relates to a file, use the fields at `file.x509`. When hashes of the DER-encoded certificate are available, the `hash` data set should be populated as well (e.g. `file.hash.sha256`). + +Events that contain certificate information about network connections, should use the x509 fields under the relevant TLS fields: `tls.server.x509` and/or `tls.client.x509`. [discrete] ==== x509 Certificate Field Details diff --git a/experimental/generated/beats/fields.ecs.yml b/experimental/generated/beats/fields.ecs.yml index da99874ab5..0514884f33 100644 --- a/experimental/generated/beats/fields.ecs.yml +++ b/experimental/generated/beats/fields.ecs.yml @@ -5884,15 +5884,18 @@ - name: x509 title: x509 Certificate group: 2 - description: This implements the common core fields for x509 certificates. This + description: 'This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files - on disk. When only a single certificate is logged in an event, it should be - nested under `file`. When hashes of the DER-encoded certificate are available, - the `hash` data set should be populated as well (e.g. `file.hash.sha256`). For - events that contain certificate information for both sides of the connection, - the x509 object could be nested under the respective side of the connection - information (e.g. `tls.server.x509`). + on disk. + + When the certificate relates to a file, use the fields at `file.x509`. When + hashes of the DER-encoded certificate are available, the `hash` data set should + be populated as well (e.g. `file.hash.sha256`). + + Events that contain certificate information about network connections, should + use the x509 fields under the relevant TLS fields: `tls.server.x509` and/or + `tls.client.x509`.' type: group fields: - name: alternative_names diff --git a/experimental/generated/ecs/ecs_nested.yml b/experimental/generated/ecs/ecs_nested.yml index bfb2df366d..6db94dce84 100644 --- a/experimental/generated/ecs/ecs_nested.yml +++ b/experimental/generated/ecs/ecs_nested.yml @@ -10357,14 +10357,16 @@ vulnerability: title: Vulnerability type: group x509: - description: This implements the common core fields for x509 certificates. This + description: 'This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable - binaries, S/MIME information in email bodies, or analysis of files on disk. When - only a single certificate is logged in an event, it should be nested under `file`. - When hashes of the DER-encoded certificate are available, the `hash` data set - should be populated as well (e.g. `file.hash.sha256`). For events that contain - certificate information for both sides of the connection, the x509 object could - be nested under the respective side of the connection information (e.g. `tls.server.x509`). + binaries, S/MIME information in email bodies, or analysis of files on disk. + + When the certificate relates to a file, use the fields at `file.x509`. When hashes + of the DER-encoded certificate are available, the `hash` data set should be populated + as well (e.g. `file.hash.sha256`). + + Events that contain certificate information about network connections, should + use the x509 fields under the relevant TLS fields: `tls.server.x509` and/or `tls.client.x509`.' fields: x509.alternative_names: dashed_name: x509-alternative-names diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index e4b1f1bb45..f1e073d6b1 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -5765,15 +5765,18 @@ - name: x509 title: x509 Certificate group: 2 - description: This implements the common core fields for x509 certificates. This + description: 'This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files - on disk. When only a single certificate is logged in an event, it should be - nested under `file`. When hashes of the DER-encoded certificate are available, - the `hash` data set should be populated as well (e.g. `file.hash.sha256`). For - events that contain certificate information for both sides of the connection, - the x509 object could be nested under the respective side of the connection - information (e.g. `tls.server.x509`). + on disk. + + When the certificate relates to a file, use the fields at `file.x509`. When + hashes of the DER-encoded certificate are available, the `hash` data set should + be populated as well (e.g. `file.hash.sha256`). + + Events that contain certificate information about network connections, should + use the x509 fields under the relevant TLS fields: `tls.server.x509` and/or + `tls.client.x509`.' type: group fields: - name: alternative_names diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 1ca8779d5e..0aa8c9d343 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -10065,14 +10065,16 @@ vulnerability: title: Vulnerability type: group x509: - description: This implements the common core fields for x509 certificates. This + description: 'This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable - binaries, S/MIME information in email bodies, or analysis of files on disk. When - only a single certificate is logged in an event, it should be nested under `file`. - When hashes of the DER-encoded certificate are available, the `hash` data set - should be populated as well (e.g. `file.hash.sha256`). For events that contain - certificate information for both sides of the connection, the x509 object could - be nested under the respective side of the connection information (e.g. `tls.server.x509`). + binaries, S/MIME information in email bodies, or analysis of files on disk. + + When the certificate relates to a file, use the fields at `file.x509`. When hashes + of the DER-encoded certificate are available, the `hash` data set should be populated + as well (e.g. `file.hash.sha256`). + + Events that contain certificate information about network connections, should + use the x509 fields under the relevant TLS fields: `tls.server.x509` and/or `tls.client.x509`.' fields: x509.alternative_names: dashed_name: x509-alternative-names diff --git a/schemas/x509.yml b/schemas/x509.yml index 06209dcbeb..124551c96c 100644 --- a/schemas/x509.yml +++ b/schemas/x509.yml @@ -6,10 +6,12 @@ description: > This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files on disk. - When only a single certificate is logged in an event, it should be nested under `file`. When hashes of the DER-encoded - certificate are available, the `hash` data set should be populated as well (e.g. `file.hash.sha256`). For events that - contain certificate information for both sides of the connection, the x509 object could be nested under the respective - side of the connection information (e.g. `tls.server.x509`). + + When the certificate relates to a file, use the fields at `file.x509`. When hashes of the DER-encoded + certificate are available, the `hash` data set should be populated as well (e.g. `file.hash.sha256`). + + Events that contain certificate information about network connections, should use the x509 fields + under the relevant TLS fields: `tls.server.x509` and/or `tls.client.x509`. type: group reusable: top_level: false