Clarify x509 definition guidance for network events with only one cert

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
 

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

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

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

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

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

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