diff --git a/CHANGELOG.md b/CHANGELOG.md index edd614a6b0..f1a5c69aa9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,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 ddcb587a24..25f01313b3 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 5352e2bb18..999a5694c3 100644 --- a/experimental/generated/beats/fields.ecs.yml +++ b/experimental/generated/beats/fields.ecs.yml @@ -5883,15 +5883,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 da428dae70..f77c396833 100644 --- a/experimental/generated/ecs/ecs_nested.yml +++ b/experimental/generated/ecs/ecs_nested.yml @@ -10375,14 +10375,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 b2d3e4ef5a..12a6db1f75 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 ca9424eaed..f8b86c0ee0 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -10084,14 +10084,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