Skip to content

Commit

Permalink
Clarify x509 definition guidance for network events with only one cert (
Browse files Browse the repository at this point in the history
  • Loading branch information
Mathieu Martin authored and ebeahan committed Dec 3, 2020
1 parent 9603f26 commit 979c603
Show file tree
Hide file tree
Showing 8 changed files with 58 additions and 39 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,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

Expand Down
13 changes: 7 additions & 6 deletions code/go/ecs/x509.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 5 additions & 1 deletion docs/field-details.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 10 additions & 7 deletions experimental/generated/beats/fields.ecs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5897,15 +5897,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
Expand Down
16 changes: 9 additions & 7 deletions experimental/generated/ecs/ecs_nested.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10396,14 +10396,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
Expand Down
17 changes: 10 additions & 7 deletions generated/beats/fields.ecs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5669,15 +5669,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
Expand Down
16 changes: 9 additions & 7 deletions generated/ecs/ecs_nested.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9988,14 +9988,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
Expand Down
10 changes: 6 additions & 4 deletions schemas/x509.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 979c603

Please sign in to comment.