diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index f60d15de27..3aa8f1c00d 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -28,14 +28,27 @@ Thanks, you're awesome :-) --> #### Improvements -* Remove misleading pluralization in the description of `user.id`, it should +* Removed misleading pluralization in the description of `user.id`, it should contain one ID, not many. #801 * Clarified misleading wording about multiple IPs in src/dst or cli/srv. #804 * Improved verbiage about the MITRE ATT&CK® framework. #866 +* Removed the default `object_type=keyword` that was being applied to `object` fields. + This attribute is Beats-specific. It's still supported, but needs to be set explicitly + on a case by case basis now. This default being removed affects `dns.answers`, + `log.syslog`, `network.inner`, `observer.egress`, and `observer.ingress`. #871 +* Improved attribute `dashed_name` in `generated/ecs/*.yml` to also + replace `@` with `-`. #871 #### Deprecated * Deprecate guidance to lowercase `http.request.method` #840 +* In `ecs_nested.yml`, we're deprecating the attribute `nestings`. It will be + removed in a future release. The deprecated `nestings` attribute was an array of + flat field names describing where fields are nested within the field set. + This is replaced with the attribute `reused_here`, which is an array of objects. + The new format still lists where the fields are nested via the same flat field name, + but also specifies additional information about each field reuse. + ### Tooling and Artifact Changes diff --git a/code/go/ecs/base.go b/code/go/ecs/base.go index 8960635b75..096641294c 100644 --- a/code/go/ecs/base.go +++ b/code/go/ecs/base.go @@ -23,8 +23,8 @@ import ( "time" ) -// The `base` field set contains all fields which are on the top level. These -// fields are common across all types of events. +// The `base` field set contains all fields which are at the root of the +// events. These fields are common across all types of events. type Base struct { // Date/time when the event originated. // This is the date/time extracted from the event, typically representing diff --git a/code/go/ecs/tls.go b/code/go/ecs/tls.go index 424a12e71a..3fd1e0e788 100644 --- a/code/go/ecs/tls.go +++ b/code/go/ecs/tls.go @@ -58,8 +58,8 @@ type Tls struct { ClientJa3 string `ecs:"client.ja3"` // Also called an SNI, this tells the server which hostname to which the - // client is attempting to connect. When this value is available, it should - // get copied to `destination.domain`. + // client is attempting to connect to. When this value is available, it + // should get copied to `destination.domain`. ClientServerName string `ecs:"client.server_name"` // Array of ciphers offered by the client during the client hello. diff --git a/code/go/ecs/x509.go b/code/go/ecs/x509.go index 5aba49e350..99d916a641 100644 --- a/code/go/ecs/x509.go +++ b/code/go/ecs/x509.go @@ -62,9 +62,9 @@ type X509 struct { // List of country (C) codes IssuerCountry string `ecs:"issuer.country"` - // Identifier for certificate signature algorithm. Recommend using names - // found in Go Lang Crypto library (See - // https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + // Identifier for certificate signature algorithm. We recommend using names + // found in Go Lang Crypto library. See + // https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. SignatureAlgorithm string `ecs:"signature_algorithm"` // Time at which the certificate is first considered valid. diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index e0d33d320e..926d2cdbc3 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -2,7 +2,7 @@ [[ecs-base]] === Base Fields -The `base` field set contains all fields which are on the top level. These fields are common across all types of events. +The `base` field set contains all fields which are at the root of the events. These fields are common across all types of events. ==== Base Field Details @@ -241,7 +241,7 @@ example: `Google LLC` The `as` fields are expected to be nested at: `client.as`, `destination.as`, `server.as`, `source.as`. -Note also that the `as` fields are not expected to be used directly at the top level. +Note also that the `as` fields are not expected to be used directly at the root of the events. @@ -698,7 +698,7 @@ example: `true` The `code_signature` fields are expected to be nested at: `dll.code_signature`, `file.code_signature`, `process.code_signature`. -Note also that the `code_signature` fields are not expected to be used directly at the top level. +Note also that the `code_signature` fields are not expected to be used directly at the root of the events. @@ -2274,7 +2274,7 @@ example: `1001` | <> -| 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`). +| These fields contain x509 certificate metadata. // =============================================================== @@ -2410,7 +2410,7 @@ example: `Quebec` The `geo` fields are expected to be nested at: `client.geo`, `destination.geo`, `host.geo`, `observer.geo`, `server.geo`, `source.geo`. -Note also that the `geo` fields are not expected to be used directly at the top level. +Note also that the `geo` fields are not expected to be used directly at the root of the events. @@ -2475,7 +2475,7 @@ type: keyword The `group` fields are expected to be nested at: `user.group`. -Note also that the `group` fields may be used directly at the top level. +Note also that the `group` fields may be used directly at the root of the events. @@ -2553,7 +2553,7 @@ type: keyword The `hash` fields are expected to be nested at: `dll.hash`, `file.hash`, `process.hash`. -Note also that the `hash` fields are not expected to be used directly at the top level. +Note also that the `hash` fields are not expected to be used directly at the root of the events. @@ -2966,7 +2966,7 @@ example: `eth0` The `interface` fields are expected to be nested at: `observer.egress.interface`, `observer.ingress.interface`. -Note also that the `interface` fields are not expected to be used directly at the top level. +Note also that the `interface` fields are not expected to be used directly at the root of the events. @@ -3822,7 +3822,7 @@ example: `10.14.1` The `os` fields are expected to be nested at: `host.os`, `observer.os`, `user_agent.os`. -Note also that the `os` fields are not expected to be used directly at the top level. +Note also that the `os` fields are not expected to be used directly at the root of the events. @@ -4129,7 +4129,7 @@ example: `Microsoft® Windows® Operating System` The `pe` fields are expected to be nested at: `dll.pe`, `file.pe`, `process.pe`. -Note also that the `pe` fields are not expected to be used directly at the top level. +Note also that the `pe` fields are not expected to be used directly at the root of the events. @@ -4412,7 +4412,7 @@ example: `/home/alice` The `process` fields are expected to be nested at: `process.parent`. -Note also that the `process` fields may be used directly at the top level. +Note also that the `process` fields may be used directly at the root of the events. @@ -5608,7 +5608,7 @@ example: `1970-01-01T00:00:00.000Z` // =============================================================== | tls.client.server_name -| Also called an SNI, this tells the server which hostname to which the client is attempting to connect. When this value is available, it should get copied to `destination.domain`. +| Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. When this value is available, it should get copied to `destination.domain`. type: keyword @@ -5878,13 +5878,13 @@ example: `tls` | <> -| 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`). +| These fields contain x509 certificate metadata. // =============================================================== | <> -| 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`). +| These fields contain x509 certificate metadata. // =============================================================== @@ -6269,7 +6269,7 @@ example: `albert` The `user` fields are expected to be nested at: `client.user`, `destination.user`, `host.user`, `server.user`, `source.user`. -Note also that the `user` fields may be used directly at the top level. +Note also that the `user` fields may be used directly at the root of the events. @@ -6441,7 +6441,7 @@ example: `outside` The `vlan` fields are expected to be nested at: `network.inner.vlan`, `network.vlan`, `observer.egress.vlan`, `observer.ingress.vlan`. -Note also that the `vlan` fields are not expected to be used directly at the top level. +Note also that the `vlan` fields are not expected to be used directly at the root of the events. @@ -6879,7 +6879,7 @@ example: `55FBB9C7DEBF09809D12CCAA` // =============================================================== | x509.signature_algorithm -| Identifier for certificate signature algorithm. Recommend using names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). +| Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. type: keyword @@ -7019,7 +7019,7 @@ example: `3` The `x509` fields are expected to be nested at: `file.x509`, `tls.client.x509`, `tls.server.x509`. -Note also that the `x509` fields are not expected to be used directly at the top level. +Note also that the `x509` fields are not expected to be used directly at the root of the events. diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc index 0f5b4b60b9..03a74e16cd 100644 --- a/docs/field-values.asciidoc +++ b/docs/field-values.asciidoc @@ -62,8 +62,6 @@ This value indicates an event that describes an alert or notable event, triggere - - [float] [[ecs-event-kind-event]] ==== event @@ -72,8 +70,6 @@ This value is the most general and most common value for this field. It is used - - [float] [[ecs-event-kind-metric]] ==== metric @@ -86,8 +82,6 @@ Metric events are often collected on a predictable frequency, such as once every - - [float] [[ecs-event-kind-state]] ==== state @@ -102,8 +96,6 @@ State events are often collected on a predictable frequency, such as once every - - [float] [[ecs-event-kind-pipeline_error]] ==== pipeline_error @@ -112,8 +104,6 @@ This value indicates that an error occurred during the ingestion of this event, - - [float] [[ecs-event-kind-signal]] ==== signal @@ -126,8 +116,6 @@ Usage of this value is reserved, and pipelines should not populate `event.kind` - - [[ecs-allowed-values-event-category]] === ECS Categorization Field: event.category @@ -164,8 +152,6 @@ that will require subsequent breaking changes. Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows event logs and ssh logs. Visualize and analyze events in this category to look for failed logins, and other authentication-related activity. - - *Expected event types for category authentication:* start, end, info @@ -178,8 +164,6 @@ start, end, info The database category denotes events and metrics relating to a data storage and retrieval system. Note that use of this category is not limited to relational database systems. Examples include event logs from MS SQL, MySQL, Elasticsearch, MongoDB, etc. Use this category to visualize and analyze database activity such as accesses and changes. - - *Expected event types for category database:* access, change, info, error @@ -194,8 +178,6 @@ Events in the driver category have to do with operating system device drivers an Use events and metrics in this category to visualize and analyze driver-related activity and status on hosts. - - *Expected event types for category driver:* change, end, info, start @@ -208,8 +190,6 @@ change, end, info, start Relating to a set of information that has been created on, or has existed on a filesystem. Use this category of events to visualize and analyze the creation, access, and deletions of files. Events in this category can come from both host-based and network-based sources. An example source of a network-based detection of a file transfer would be the Zeek file.log. - - *Expected event types for category file:* change, creation, deletion, info @@ -226,8 +206,6 @@ Most of the events in this category can usually be observed from the outside, su Note that this category is for information about hosts themselves; it is not meant to capture activity "happening on a host". - - *Expected event types for category host:* access, change, end, info, start @@ -240,8 +218,6 @@ access, change, end, info, start Identity and access management (IAM) events relating to users, groups, and administration. Use this category to visualize and analyze IAM-related logs and data from active directory, LDAP, Okta, Duo, and other IAM systems. - - *Expected event types for category iam:* admin, change, creation, deletion, group, info, user @@ -254,8 +230,6 @@ admin, change, creation, deletion, group, info, user Relating to intrusion detections from IDS/IPS systems and functions, both network and host-based. Use this category to visualize and analyze intrusion detection alerts from systems such as Snort, Suricata, and Palo Alto threat detections. - - *Expected event types for category intrusion_detection:* allowed, denied, info @@ -268,8 +242,6 @@ allowed, denied, info Malware detection events and alerts. Use this category to visualize and analyze malware detections from EDR/EPP systems such as Elastic Endpoint Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems such as Suricata, or other sources of malware-related events such as Palo Alto Networks threat logs and Wildfire logs. - - *Expected event types for category malware:* info @@ -282,8 +254,6 @@ info Relating to all network activity, including network connection lifecycle, network traffic, and essentially any event that includes an IP address. Many events containing decoded network protocol transactions fit into this category. Use events in this category to visualize or analyze counts of network ports, protocols, addresses, geolocation information, etc. - - *Expected event types for category network:* access, allowed, connection, denied, end, info, protocol, start @@ -296,8 +266,6 @@ access, allowed, connection, denied, end, info, protocol, start Relating to software packages installed on hosts. Use this category to visualize and analyze inventory of software installed on various hosts, or to determine host vulnerability in the absence of vulnerability scan data. - - *Expected event types for category package:* access, change, deletion, info, installation, start @@ -310,8 +278,6 @@ access, change, deletion, info, installation, start Use this category of events to visualize and analyze process-specific information such as lifecycle events or process ancestry. - - *Expected event types for category process:* access, change, end, info, start @@ -324,8 +290,6 @@ access, change, end, info, start Relating to web server access. Use this category to create a dashboard of web server/proxy activity from apache, IIS, nginx web servers, etc. Note: events from network observers such as Zeek http log may also be included in this category. - - *Expected event types for category web:* access, error, info @@ -372,8 +336,6 @@ The access event type is used for the subset of events within a category that in - - [float] [[ecs-event-type-admin]] ==== admin @@ -382,8 +344,6 @@ The admin event type is used for the subset of events within a category that are - - [float] [[ecs-event-type-allowed]] ==== allowed @@ -392,8 +352,6 @@ The allowed event type is used for the subset of events within a category that i - - [float] [[ecs-event-type-change]] ==== change @@ -402,8 +360,6 @@ The change event type is used for the subset of events within a category that in - - [float] [[ecs-event-type-connection]] ==== connection @@ -412,8 +368,6 @@ Used primarily with `event.category:network` this value is used for the subset o - - [float] [[ecs-event-type-creation]] ==== creation @@ -422,8 +376,6 @@ The "creation" event type is used for the subset of events within a category tha - - [float] [[ecs-event-type-deletion]] ==== deletion @@ -432,8 +384,6 @@ The deletion event type is used for the subset of events within a category that - - [float] [[ecs-event-type-denied]] ==== denied @@ -442,8 +392,6 @@ The denied event type is used for the subset of events within a category that in - - [float] [[ecs-event-type-end]] ==== end @@ -452,8 +400,6 @@ The end event type is used for the subset of events within a category that indic - - [float] [[ecs-event-type-error]] ==== error @@ -462,8 +408,6 @@ The error event type is used for the subset of events within a category that ind - - [float] [[ecs-event-type-group]] ==== group @@ -472,8 +416,6 @@ The group event type is used for the subset of events within a category that are - - [float] [[ecs-event-type-info]] ==== info @@ -482,8 +424,6 @@ The info event type is used for the subset of events within a category that indi - - [float] [[ecs-event-type-installation]] ==== installation @@ -492,8 +432,6 @@ The installation event type is used for the subset of events within a category t - - [float] [[ecs-event-type-protocol]] ==== protocol @@ -501,8 +439,6 @@ The installation event type is used for the subset of events within a category t The protocol event type is used for the subset of events within a category that indicate that they contain protocol details or analysis, beyond simply identifying the protocol. Generally, network events that contain specific protocol details will fall into this subcategory. A common example is `event.category:network AND event.type:protocol AND event.type:connection AND event.type:end` (to indicate that the event is a network connection event sent at the end of a connection that also includes a protocol detail breakdown). Note that events that only indicate the name or id of the protocol should not use the protocol value. Further note that when the protocol subcategory is used, the identified protocol is populated in the ECS `network.protocol` field. - - *Expected event types for category protocol:* access, change, end, info, start @@ -516,8 +452,6 @@ The start event type is used for the subset of events within a category that ind - - [float] [[ecs-event-type-user]] ==== user @@ -526,8 +460,6 @@ The user event type is used for the subset of events within a category that are - - [[ecs-allowed-values-event-outcome]] === ECS Categorization Field: event.outcome @@ -560,8 +492,6 @@ Indicates that this event describes a failed result. A common example is `event. - - [float] [[ecs-event-outcome-success]] ==== success @@ -570,8 +500,6 @@ Indicates that this event describes a successful result. A common example is `ev - - [float] [[ecs-event-outcome-unknown]] ==== unknown @@ -579,5 +507,3 @@ Indicates that this event describes a successful result. A common example is `ev Indicates that this event describes only an attempt for which the result is unknown from the perspective of the event producer. For example, if the event contains information only about the request side of a transaction that results in a response, populating `event.outcome:unknown` in the request event is appropriate. The unknown value should not be used when an outcome doesn't make logical sense for the event. In such cases `event.outcome` should not be populated. - - diff --git a/docs/fields.asciidoc b/docs/fields.asciidoc index ead1723d98..9200f84a2a 100644 --- a/docs/fields.asciidoc +++ b/docs/fields.asciidoc @@ -18,7 +18,7 @@ all fields are defined. |===== | Field Set | Description -| <> | All fields defined directly at the top level +| <> | All fields defined directly at the root of the events. | <> | Fields about the monitoring agent. @@ -102,7 +102,7 @@ all fields are defined. | <> | Fields to describe the vulnerability relevant to an event. -| <> | 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`). +| <> | These fields contain x509 certificate metadata. |===== diff --git a/generated/README.md b/generated/README.md index 76dfc10266..3972963bae 100644 --- a/generated/README.md +++ b/generated/README.md @@ -10,11 +10,13 @@ In this directory, you'll find the following: * `csv/fields.csv`: A csv file you can use to import ECS field definitions in a spreadsheet. -* `ecs/*.yml`: Two files that are the fully fleshed out representation of ECS. - All the default values are filled in, basic checks have been made to ensure - correctness or consistency, etc. - Generators literally operate on one of these two representations, depending on - whether they depend on the variables `ecs_flat` or `ecs_nested`. +* `ecs/*.yml`: These are the files you should use, if you need to consume ECS + programmatically. This repo's artifact generators all operate based off of one + of these two representations (documentation, csv, Elasticsearch + template, etc). + The two files are the fully fleshed out representation of ECS: + default values are filled in, all fields being reused elsewhere are made explicit, + additional attributes are computed. * `elasticsearch/{6,7}/template.json`: Sample Elasticsearch templates to get started using ECS. Check out how to use them in diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index 8cbcd7720e..6424ac9349 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -939,7 +939,6 @@ - name: answers level: extended type: object - object_type: keyword description: 'An array containing an object for each answer section returned by the server. @@ -1825,8 +1824,8 @@ level: extended type: keyword ignore_above: 1024 - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA default_field: false - name: x509.subject.common_name @@ -2441,7 +2440,6 @@ - name: syslog level: extended type: object - object_type: keyword description: The Syslog metadata of the event, if the event was transmitted via Syslog. Please see RFCs 5424 or 3164. - name: syslog.facility.code @@ -2558,7 +2556,6 @@ - name: inner level: extended type: object - object_type: keyword description: Network.inner fields are added in addition to network.vlan fields to describe the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include vlan.id and vlan.name. Inner vlan fields are typically used @@ -2656,7 +2653,6 @@ - name: egress level: extended type: object - object_type: keyword description: Observer.egress holds information like interface number and name, vlan, and zone information to classify egress traffic. Single armed monitoring such as a network sensor on a span port should only use observer.ingress @@ -2769,7 +2765,6 @@ - name: ingress level: extended type: object - object_type: keyword description: Observer.ingress holds information like interface number and name, vlan, and zone information to classify ingress traffic. Single armed monitoring such as a network sensor on a span port should only use observer.ingress @@ -4605,7 +4600,7 @@ type: keyword ignore_above: 1024 description: Also called an SNI, this tells the server which hostname to which - the client is attempting to connect. When this value is available, it should + the client is attempting to connect to. When this value is available, it should get copied to `destination.domain`. example: www.elastic.co default_field: false @@ -4739,8 +4734,8 @@ level: extended type: keyword ignore_above: 1024 - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA default_field: false - name: client.x509.subject.common_name @@ -5022,8 +5017,8 @@ level: extended type: keyword ignore_above: 1024 - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA default_field: false - name: server.x509.subject.common_name @@ -5698,8 +5693,8 @@ level: extended type: keyword ignore_above: 1024 - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA default_field: false - name: subject.common_name diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv index 0e8b495bef..a59aea8c73 100644 --- a/generated/csv/fields.csv +++ b/generated/csv/fields.csv @@ -10,7 +10,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,agent,agent.type,keyword,core,,filebeat,Type of the agent. 1.6.0-dev,true,agent,agent.version,keyword,core,,6.0.0-rc2,Version of the agent. 1.6.0-dev,true,client,client.address,keyword,extended,,,Client network address. -1.6.0-dev,true,client,client.as.number,long,extended,,15169,Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. +1.6.0-dev,true,client,client.as.number,long,extended,,15169,Unique number allocated to the autonomous system. 1.6.0-dev,true,client,client.as.organization.name,keyword,extended,,Google LLC,Organization name. 1.6.0-dev,true,client,client.as.organization.name.text,text,extended,,Google LLC,Organization name. 1.6.0-dev,true,client,client.bytes,long,core,,184,Bytes sent from the client to the server. @@ -59,7 +59,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,container,container.name,keyword,extended,,,Container name. 1.6.0-dev,true,container,container.runtime,keyword,extended,,docker,Runtime managing this container. 1.6.0-dev,true,destination,destination.address,keyword,extended,,,Destination network address. -1.6.0-dev,true,destination,destination.as.number,long,extended,,15169,Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. +1.6.0-dev,true,destination,destination.as.number,long,extended,,15169,Unique number allocated to the autonomous system. 1.6.0-dev,true,destination,destination.as.organization.name,keyword,extended,,Google LLC,Organization name. 1.6.0-dev,true,destination,destination.as.organization.name.text,text,extended,,Google LLC,Organization name. 1.6.0-dev,true,destination,destination.bytes,long,core,,184,Bytes sent from the destination to the source. @@ -113,11 +113,11 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,dns,dns.answers.class,keyword,extended,,IN,The class of DNS data contained in this resource record. 1.6.0-dev,true,dns,dns.answers.data,keyword,extended,,10.10.10.10,The data describing the resource. 1.6.0-dev,true,dns,dns.answers.name,keyword,extended,,www.google.com,The domain name to which this resource record pertains. -1.6.0-dev,true,dns,dns.answers.ttl,long,extended,,180,The time interval in seconds that this resource record may be cached before it should be discarded. Zero values mean that the data should not be cached. +1.6.0-dev,true,dns,dns.answers.ttl,long,extended,,180,The time interval in seconds that this resource record may be cached before it should be discarded. 1.6.0-dev,true,dns,dns.answers.type,keyword,extended,,CNAME,The type of data contained in this resource record. 1.6.0-dev,true,dns,dns.header_flags,keyword,extended,array,"['RD', 'RA']",Array of DNS header flags. 1.6.0-dev,true,dns,dns.id,keyword,extended,,62111,The DNS packet identifier assigned by the program that generated the query. The identifier is copied to the response. -1.6.0-dev,true,dns,dns.op_code,keyword,extended,,QUERY,The DNS operation code that specifies the kind of query in the message. This value is set by the originator of a query and copied into the response. +1.6.0-dev,true,dns,dns.op_code,keyword,extended,,QUERY,The DNS operation code that specifies the kind of query in the message. 1.6.0-dev,true,dns,dns.question.class,keyword,extended,,IN,The class of records being queried. 1.6.0-dev,true,dns,dns.question.name,keyword,extended,,www.google.com,The name being queried. 1.6.0-dev,true,dns,dns.question.registered_domain,keyword,extended,,google.com,"The highest registered domain, stripped of the subdomain." @@ -197,7 +197,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,file,file.target_path.text,text,extended,,,Target path for symlinks. 1.6.0-dev,true,file,file.type,keyword,extended,,file,"File type (file, dir, or symlink)." 1.6.0-dev,true,file,file.uid,keyword,extended,,1001,The user ID (UID) or security identifier (SID) of the file owner. -1.6.0-dev,true,file,file.x509.alternative_names,keyword,extended,array,*.elastic.co,"List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses." +1.6.0-dev,true,file,file.x509.alternative_names,keyword,extended,array,*.elastic.co,List of subject alternative names (SAN). 1.6.0-dev,true,file,file.x509.issuer.common_name,keyword,extended,array,DigiCert SHA2 High Assurance Server CA,List of common name (CN) of issuing certificate authority. 1.6.0-dev,true,file,file.x509.issuer.country,keyword,extended,array,US,List of country (C) codes 1.6.0-dev,true,file,file.x509.issuer.distinguished_name,keyword,extended,,"C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert SHA2 High Assurance Server CA",Distinguished name (DN) of issuing certificate authority. @@ -211,8 +211,8 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,file,file.x509.public_key_curve,keyword,extended,,nistp521,The curve used by the elliptic curve public key algorithm. This is algorithm specific. 1.6.0-dev,false,file,file.x509.public_key_exponent,long,extended,,65537,Exponent used to derive the public key. This is algorithm specific. 1.6.0-dev,true,file,file.x509.public_key_size,long,extended,,2048,The size of the public key space in bits. -1.6.0-dev,true,file,file.x509.serial_number,keyword,extended,,55FBB9C7DEBF09809D12CCAA,"Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters." -1.6.0-dev,true,file,file.x509.signature_algorithm,keyword,extended,,SHA256-RSA,Identifier for certificate signature algorithm. Recommend using names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). +1.6.0-dev,true,file,file.x509.serial_number,keyword,extended,,55FBB9C7DEBF09809D12CCAA,Unique serial number issued by the certificate authority. +1.6.0-dev,true,file,file.x509.signature_algorithm,keyword,extended,,SHA256-RSA,Identifier for certificate signature algorithm. 1.6.0-dev,true,file,file.x509.subject.common_name,keyword,extended,array,r2.shared.global.fastly.net,List of common names (CN) of subject. 1.6.0-dev,true,file,file.x509.subject.country,keyword,extended,array,US,List of country (C) code 1.6.0-dev,true,file,file.x509.subject.distinguished_name,keyword,extended,,"C=US, ST=California, L=San Francisco, O=Fastly, Inc., CN=r2.shared.global.fastly.net",Distinguished name (DN) of the certificate subject entity. @@ -451,7 +451,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,rule,rule.uuid,keyword,extended,,1100110011,Rule UUID 1.6.0-dev,true,rule,rule.version,keyword,extended,,1.1,Rule version 1.6.0-dev,true,server,server.address,keyword,extended,,,Server network address. -1.6.0-dev,true,server,server.as.number,long,extended,,15169,Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. +1.6.0-dev,true,server,server.as.number,long,extended,,15169,Unique number allocated to the autonomous system. 1.6.0-dev,true,server,server.as.organization.name,keyword,extended,,Google LLC,Organization name. 1.6.0-dev,true,server,server.as.organization.name.text,text,extended,,Google LLC,Organization name. 1.6.0-dev,true,server,server.bytes,long,core,,184,Bytes sent from the server to the client. @@ -491,7 +491,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,service,service.type,keyword,core,,elasticsearch,The type of the service. 1.6.0-dev,true,service,service.version,keyword,core,,3.2.4,Version of the service. 1.6.0-dev,true,source,source.address,keyword,extended,,,Source network address. -1.6.0-dev,true,source,source.as.number,long,extended,,15169,Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. +1.6.0-dev,true,source,source.as.number,long,extended,,15169,Unique number allocated to the autonomous system. 1.6.0-dev,true,source,source.as.organization.name,keyword,extended,,Google LLC,Organization name. 1.6.0-dev,true,source,source.as.organization.name.text,text,extended,,Google LLC,Organization name. 1.6.0-dev,true,source,source.bytes,long,core,,184,Bytes sent from the source to the destination. @@ -532,19 +532,19 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,threat,threat.technique.name.text,text,extended,,Endpoint Denial of Service,Threat technique name. 1.6.0-dev,true,threat,threat.technique.reference,keyword,extended,array,https://attack.mitre.org/techniques/T1499/,Threat technique URL reference. 1.6.0-dev,true,tls,tls.cipher,keyword,extended,,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,String indicating the cipher used during the current connection. -1.6.0-dev,true,tls,tls.client.certificate,keyword,extended,,MII...,PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. -1.6.0-dev,true,tls,tls.client.certificate_chain,keyword,extended,array,"['MII...', 'MII...']",Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. -1.6.0-dev,true,tls,tls.client.hash.md5,keyword,extended,,0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC,"Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash." -1.6.0-dev,true,tls,tls.client.hash.sha1,keyword,extended,,9E393D93138888D288266C2D915214D1D1CCEB2A,"Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash." -1.6.0-dev,true,tls,tls.client.hash.sha256,keyword,extended,,0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0,"Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash." +1.6.0-dev,true,tls,tls.client.certificate,keyword,extended,,MII...,PEM-encoded stand-alone certificate offered by the client. +1.6.0-dev,true,tls,tls.client.certificate_chain,keyword,extended,array,"['MII...', 'MII...']",Array of PEM-encoded certificates that make up the certificate chain offered by the client. +1.6.0-dev,true,tls,tls.client.hash.md5,keyword,extended,,0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC,Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. +1.6.0-dev,true,tls,tls.client.hash.sha1,keyword,extended,,9E393D93138888D288266C2D915214D1D1CCEB2A,Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. +1.6.0-dev,true,tls,tls.client.hash.sha256,keyword,extended,,0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0,Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. 1.6.0-dev,true,tls,tls.client.issuer,keyword,extended,,"CN=MyDomain Root CA, OU=Infrastructure Team, DC=mydomain, DC=com",Distinguished name of subject of the issuer of the x.509 certificate presented by the client. 1.6.0-dev,true,tls,tls.client.ja3,keyword,extended,,d4e5b18d6b55c71272893221c96ba240,A hash that identifies clients based on how they perform an SSL/TLS handshake. 1.6.0-dev,true,tls,tls.client.not_after,date,extended,,2021-01-01T00:00:00.000Z,Date/Time indicating when client certificate is no longer considered valid. 1.6.0-dev,true,tls,tls.client.not_before,date,extended,,1970-01-01T00:00:00.000Z,Date/Time indicating when client certificate is first considered valid. -1.6.0-dev,true,tls,tls.client.server_name,keyword,extended,,www.elastic.co,"Also called an SNI, this tells the server which hostname to which the client is attempting to connect. When this value is available, it should get copied to `destination.domain`." +1.6.0-dev,true,tls,tls.client.server_name,keyword,extended,,www.elastic.co,Hostname the client is trying to connect to. Also called the SNI. 1.6.0-dev,true,tls,tls.client.subject,keyword,extended,,"CN=myclient, OU=Documentation Team, DC=mydomain, DC=com",Distinguished name of subject of the x.509 certificate presented by the client. 1.6.0-dev,true,tls,tls.client.supported_ciphers,keyword,extended,array,"['TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384', 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384', '...']",Array of ciphers offered by the client during the client hello. -1.6.0-dev,true,tls,tls.client.x509.alternative_names,keyword,extended,array,*.elastic.co,"List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses." +1.6.0-dev,true,tls,tls.client.x509.alternative_names,keyword,extended,array,*.elastic.co,List of subject alternative names (SAN). 1.6.0-dev,true,tls,tls.client.x509.issuer.common_name,keyword,extended,array,DigiCert SHA2 High Assurance Server CA,List of common name (CN) of issuing certificate authority. 1.6.0-dev,true,tls,tls.client.x509.issuer.country,keyword,extended,array,US,List of country (C) codes 1.6.0-dev,true,tls,tls.client.x509.issuer.distinguished_name,keyword,extended,,"C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert SHA2 High Assurance Server CA",Distinguished name (DN) of issuing certificate authority. @@ -558,8 +558,8 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,tls,tls.client.x509.public_key_curve,keyword,extended,,nistp521,The curve used by the elliptic curve public key algorithm. This is algorithm specific. 1.6.0-dev,false,tls,tls.client.x509.public_key_exponent,long,extended,,65537,Exponent used to derive the public key. This is algorithm specific. 1.6.0-dev,true,tls,tls.client.x509.public_key_size,long,extended,,2048,The size of the public key space in bits. -1.6.0-dev,true,tls,tls.client.x509.serial_number,keyword,extended,,55FBB9C7DEBF09809D12CCAA,"Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters." -1.6.0-dev,true,tls,tls.client.x509.signature_algorithm,keyword,extended,,SHA256-RSA,Identifier for certificate signature algorithm. Recommend using names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). +1.6.0-dev,true,tls,tls.client.x509.serial_number,keyword,extended,,55FBB9C7DEBF09809D12CCAA,Unique serial number issued by the certificate authority. +1.6.0-dev,true,tls,tls.client.x509.signature_algorithm,keyword,extended,,SHA256-RSA,Identifier for certificate signature algorithm. 1.6.0-dev,true,tls,tls.client.x509.subject.common_name,keyword,extended,array,r2.shared.global.fastly.net,List of common names (CN) of subject. 1.6.0-dev,true,tls,tls.client.x509.subject.country,keyword,extended,array,US,List of country (C) code 1.6.0-dev,true,tls,tls.client.x509.subject.distinguished_name,keyword,extended,,"C=US, ST=California, L=San Francisco, O=Fastly, Inc., CN=r2.shared.global.fastly.net",Distinguished name (DN) of the certificate subject entity. @@ -570,19 +570,19 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,tls,tls.client.x509.version_number,keyword,extended,,3,Version of x509 format. 1.6.0-dev,true,tls,tls.curve,keyword,extended,,secp256r1,"String indicating the curve used for the given cipher, when applicable." 1.6.0-dev,true,tls,tls.established,boolean,extended,,,Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. -1.6.0-dev,true,tls,tls.next_protocol,keyword,extended,,http/1.1,"String indicating the protocol being tunneled. Per the values in the IANA registry (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), this string should be lower case." +1.6.0-dev,true,tls,tls.next_protocol,keyword,extended,,http/1.1,String indicating the protocol being tunneled. 1.6.0-dev,true,tls,tls.resumed,boolean,extended,,,Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. -1.6.0-dev,true,tls,tls.server.certificate,keyword,extended,,MII...,PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. -1.6.0-dev,true,tls,tls.server.certificate_chain,keyword,extended,array,"['MII...', 'MII...']",Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. -1.6.0-dev,true,tls,tls.server.hash.md5,keyword,extended,,0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC,"Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash." -1.6.0-dev,true,tls,tls.server.hash.sha1,keyword,extended,,9E393D93138888D288266C2D915214D1D1CCEB2A,"Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash." -1.6.0-dev,true,tls,tls.server.hash.sha256,keyword,extended,,0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0,"Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash." +1.6.0-dev,true,tls,tls.server.certificate,keyword,extended,,MII...,PEM-encoded stand-alone certificate offered by the server. +1.6.0-dev,true,tls,tls.server.certificate_chain,keyword,extended,array,"['MII...', 'MII...']",Array of PEM-encoded certificates that make up the certificate chain offered by the server. +1.6.0-dev,true,tls,tls.server.hash.md5,keyword,extended,,0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC,Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. +1.6.0-dev,true,tls,tls.server.hash.sha1,keyword,extended,,9E393D93138888D288266C2D915214D1D1CCEB2A,Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. +1.6.0-dev,true,tls,tls.server.hash.sha256,keyword,extended,,0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0,Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. 1.6.0-dev,true,tls,tls.server.issuer,keyword,extended,,"CN=MyDomain Root CA, OU=Infrastructure Team, DC=mydomain, DC=com",Subject of the issuer of the x.509 certificate presented by the server. 1.6.0-dev,true,tls,tls.server.ja3s,keyword,extended,,394441ab65754e2207b1e1b457b3641d,A hash that identifies servers based on how they perform an SSL/TLS handshake. 1.6.0-dev,true,tls,tls.server.not_after,date,extended,,2021-01-01T00:00:00.000Z,Timestamp indicating when server certificate is no longer considered valid. 1.6.0-dev,true,tls,tls.server.not_before,date,extended,,1970-01-01T00:00:00.000Z,Timestamp indicating when server certificate is first considered valid. 1.6.0-dev,true,tls,tls.server.subject,keyword,extended,,"CN=www.mydomain.com, OU=Infrastructure Team, DC=mydomain, DC=com",Subject of the x.509 certificate presented by the server. -1.6.0-dev,true,tls,tls.server.x509.alternative_names,keyword,extended,array,*.elastic.co,"List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses." +1.6.0-dev,true,tls,tls.server.x509.alternative_names,keyword,extended,array,*.elastic.co,List of subject alternative names (SAN). 1.6.0-dev,true,tls,tls.server.x509.issuer.common_name,keyword,extended,array,DigiCert SHA2 High Assurance Server CA,List of common name (CN) of issuing certificate authority. 1.6.0-dev,true,tls,tls.server.x509.issuer.country,keyword,extended,array,US,List of country (C) codes 1.6.0-dev,true,tls,tls.server.x509.issuer.distinguished_name,keyword,extended,,"C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert SHA2 High Assurance Server CA",Distinguished name (DN) of issuing certificate authority. @@ -596,8 +596,8 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 1.6.0-dev,true,tls,tls.server.x509.public_key_curve,keyword,extended,,nistp521,The curve used by the elliptic curve public key algorithm. This is algorithm specific. 1.6.0-dev,false,tls,tls.server.x509.public_key_exponent,long,extended,,65537,Exponent used to derive the public key. This is algorithm specific. 1.6.0-dev,true,tls,tls.server.x509.public_key_size,long,extended,,2048,The size of the public key space in bits. -1.6.0-dev,true,tls,tls.server.x509.serial_number,keyword,extended,,55FBB9C7DEBF09809D12CCAA,"Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters." -1.6.0-dev,true,tls,tls.server.x509.signature_algorithm,keyword,extended,,SHA256-RSA,Identifier for certificate signature algorithm. Recommend using names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). +1.6.0-dev,true,tls,tls.server.x509.serial_number,keyword,extended,,55FBB9C7DEBF09809D12CCAA,Unique serial number issued by the certificate authority. +1.6.0-dev,true,tls,tls.server.x509.signature_algorithm,keyword,extended,,SHA256-RSA,Identifier for certificate signature algorithm. 1.6.0-dev,true,tls,tls.server.x509.subject.common_name,keyword,extended,array,r2.shared.global.fastly.net,List of common names (CN) of subject. 1.6.0-dev,true,tls,tls.server.x509.subject.country,keyword,extended,array,US,List of country (C) code 1.6.0-dev,true,tls,tls.server.x509.subject.distinguished_name,keyword,extended,,"C=US, ST=California, L=San Francisco, O=Fastly, Inc., CN=r2.shared.global.fastly.net",Distinguished name (DN) of the certificate subject entity. diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml index a6571636dc..e0bcd2a197 100644 --- a/generated/ecs/ecs_flat.yml +++ b/generated/ecs/ecs_flat.yml @@ -1,5 +1,5 @@ '@timestamp': - dashed_name: '@timestamp' + dashed_name: -timestamp description: 'Date/time when the event originated. This is the date/time extracted from the event, typically representing when the @@ -126,8 +126,7 @@ client.as.number: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system number - (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long client.as.organization.name: dashed_name: client-as-organization-name @@ -692,8 +691,7 @@ destination.as.number: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system number - (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long destination.as.organization.name: dashed_name: destination-as-organization-name @@ -1291,7 +1289,6 @@ dns.answers: name: answers normalize: - array - object_type: keyword short: Array of DNS answers. type: object dns.answers.class: @@ -1343,7 +1340,7 @@ dns.answers.ttl: name: answers.ttl normalize: [] short: The time interval in seconds that this resource record may be cached before - it should be discarded. Zero values mean that the data should not be cached. + it should be discarded. type: long dns.answers.type: dashed_name: dns-answers-type @@ -1395,8 +1392,7 @@ dns.op_code: level: extended name: op_code normalize: [] - short: The DNS operation code that specifies the kind of query in the message. This - value is set by the originator of a query and copied into the response. + short: The DNS operation code that specifies the kind of query in the message. type: keyword dns.question.class: dashed_name: dns-question-class @@ -1623,25 +1619,21 @@ event.action: type: keyword event.category: allowed_values: - - description: 'Events in this category are related to the challenge and response + - description: Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows event logs and ssh logs. Visualize and analyze events in this category to look for failed logins, and other authentication-related activity. - - ' expected_event_types: - start - end - info name: authentication - - description: 'The database category denotes events and metrics relating to a data + - description: The database category denotes events and metrics relating to a data storage and retrieval system. Note that use of this category is not limited to relational database systems. Examples include event logs from MS SQL, MySQL, Elasticsearch, MongoDB, etc. Use this category to visualize and analyze database activity such as accesses and changes. - - ' expected_event_types: - access - change @@ -1653,22 +1645,18 @@ event.category: kernel modules, etc. Use events and metrics in this category to visualize and analyze driver-related - activity and status on hosts. - - ' + activity and status on hosts.' expected_event_types: - change - end - info - start name: driver - - description: 'Relating to a set of information that has been created on, or has + - description: Relating to a set of information that has been created on, or has existed on a filesystem. Use this category of events to visualize and analyze the creation, access, and deletions of files. Events in this category can come from both host-based and network-based sources. An example source of a network-based detection of a file transfer would be the Zeek file.log. - - ' expected_event_types: - change - creation @@ -1683,9 +1671,7 @@ event.category: be seen from within, such as "start" or "end". Note that this category is for information about hosts themselves; it is not - meant to capture activity "happening on a host". - - ' + meant to capture activity "happening on a host".' expected_event_types: - access - change @@ -1693,11 +1679,9 @@ event.category: - info - start name: host - - description: 'Identity and access management (IAM) events relating to users, groups, + - description: Identity and access management (IAM) events relating to users, groups, and administration. Use this category to visualize and analyze IAM-related logs and data from active directory, LDAP, Okta, Duo, and other IAM systems. - - ' expected_event_types: - admin - change @@ -1707,34 +1691,28 @@ event.category: - info - user name: iam - - description: 'Relating to intrusion detections from IDS/IPS systems and functions, + - description: Relating to intrusion detections from IDS/IPS systems and functions, both network and host-based. Use this category to visualize and analyze intrusion detection alerts from systems such as Snort, Suricata, and Palo Alto threat detections. - - ' expected_event_types: - allowed - denied - info name: intrusion_detection - - description: 'Malware detection events and alerts. Use this category to visualize + - description: Malware detection events and alerts. Use this category to visualize and analyze malware detections from EDR/EPP systems such as Elastic Endpoint Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems such as Suricata, or other sources of malware-related events such as Palo Alto Networks threat logs and Wildfire logs. - - ' expected_event_types: - info name: malware - - description: 'Relating to all network activity, including network connection lifecycle, + - description: Relating to all network activity, including network connection lifecycle, network traffic, and essentially any event that includes an IP address. Many events containing decoded network protocol transactions fit into this category. Use events in this category to visualize or analyze counts of network ports, protocols, addresses, geolocation information, etc. - - ' expected_event_types: - access - allowed @@ -1745,11 +1723,9 @@ event.category: - protocol - start name: network - - description: 'Relating to software packages installed on hosts. Use this category + - description: Relating to software packages installed on hosts. Use this category to visualize and analyze inventory of software installed on various hosts, or to determine host vulnerability in the absence of vulnerability scan data. - - ' expected_event_types: - access - change @@ -1758,10 +1734,8 @@ event.category: - installation - start name: package - - description: 'Use this category of events to visualize and analyze process-specific + - description: Use this category of events to visualize and analyze process-specific information such as lifecycle events or process ancestry. - - ' expected_event_types: - access - change @@ -1772,9 +1746,7 @@ event.category: - description: 'Relating to web server access. Use this category to create a dashboard of web server/proxy activity from apache, IIS, nginx web servers, etc. Note: events from network observers such as Zeek http log may also be included in - this category. - - ' + this category.' expected_event_types: - access - error @@ -1926,14 +1898,10 @@ event.kind: event, triggered by a detection rule. `event.kind:alert` is often populated for events coming from firewalls, intrusion - detection systems, endpoint detection and response systems, and so on. - - ' + detection systems, endpoint detection and response systems, and so on.' name: alert - - description: 'This value is the most general and most common value for this field. + - description: This value is the most general and most common value for this field. It is used to represent events that indicate that something happened. - - ' name: event - description: 'This value is used to indicate that this event describes a numeric measurement taken at given point in time. @@ -1942,9 +1910,7 @@ event.kind: Metric events are often collected on a predictable frequency, such as once every few seconds, or once a minute, but can also be used to describe ad-hoc numeric - metric queries. - - ' + metric queries.' name: metric - description: 'The state value is similar to metric, indicating that this event describes a measurement taken at given point in time, except that the measurement @@ -1963,15 +1929,11 @@ event.kind: State events are often collected on a predictable frequency, such as once every few seconds, once a minute, once an hour, or once a day, but can also be used - to describe ad-hoc state queries. - - ' + to describe ad-hoc state queries.' name: state - - description: 'This value indicates that an error occurred during the ingestion + - description: This value indicates that an error occurred during the ingestion of this event, and that event data may be missing, inconsistent, or incorrect. `event.kind:pipeline_error` is often associated with parsing errors. - - ' name: pipeline_error - description: 'This value is used by the Elastic SIEM app to denote an Elasticsearch document that was created by a SIEM detection engine rule. @@ -1980,9 +1942,7 @@ event.kind: and should be investigated. Usage of this value is reserved, and pipelines should not populate `event.kind` - with the value "signal". - - ' + with the value "signal".' name: signal dashed_name: event-kind description: 'This is one of four ECS Categorization Fields, and indicates the highest @@ -2037,27 +1997,21 @@ event.original: type: keyword event.outcome: allowed_values: - - description: 'Indicates that this event describes a failed result. A common example + - description: Indicates that this event describes a failed result. A common example is `event.category:file AND event.type:access AND event.outcome:failure` to indicate that a file access was attempted, but was not successful. - - ' name: failure - - description: 'Indicates that this event describes a successful result. A common + - description: Indicates that this event describes a successful result. A common example is `event.category:file AND event.type:create AND event.outcome:success` to indicate that a file was successfully created. - - ' name: success - - description: 'Indicates that this event describes only an attempt for which the + - description: Indicates that this event describes only an attempt for which the result is unknown from the perspective of the event producer. For example, if the event contains information only about the request side of a transaction that results in a response, populating `event.outcome:unknown` in the request - event is appropriate. The unknown value should not be used when an outcome doesn''t + event is appropriate. The unknown value should not be used when an outcome doesn't make logical sense for the event. In such cases `event.outcome` should not be populated. - - ' name: unknown dashed_name: event-outcome description: 'This is one of four ECS Categorization Fields, and indicates the lowest @@ -2198,14 +2152,12 @@ event.timezone: type: keyword event.type: allowed_values: - - description: 'The access event type is used for the subset of events within a - category that indicate that something was accessed. Common examples include - `event.category:database AND event.type:access`, or `event.category:file AND - event.type:access`. Note for file access, both directory listings and file opens - should be included in this subcategory. You can further distinguish access operations - using the ECS `event.action` field. - - ' + - description: The access event type is used for the subset of events within a category + that indicate that something was accessed. Common examples include `event.category:database + AND event.type:access`, or `event.category:file AND event.type:access`. Note + for file access, both directory listings and file opens should be included in + this subcategory. You can further distinguish access operations using the ECS + `event.action` field. name: access - description: 'The admin event type is used for the subset of events within a category that are related to admin objects. For example, administrative changes within @@ -2213,11 +2165,9 @@ event.type: new applications to a federation solution or connecting discrete forests in Active Directory) would fall into this subcategory. Common example: `event.category:iam AND event.type:change AND event.type:admin`. You can further distinguish admin - operations using the ECS `event.action` field. - - ' + operations using the ECS `event.action` field.' name: admin - - description: 'The allowed event type is used for the subset of events within a + - description: The allowed event type is used for the subset of events within a category that indicate that something was allowed. Common examples include `event.category:network AND event.type:connection AND event.type:allowed` (to indicate a network firewall event for which the firewall disposition was to allow the connection to complete) @@ -2226,22 +2176,18 @@ event.type: to allow the connection to complete). You can further distinguish allowed operations using the ECS `event.action` field, populating with values of your choosing, such as "allow", "detect", or "pass". - - ' name: allowed - - description: 'The change event type is used for the subset of events within a - category that indicate that something has changed. If semantics best describe - an event as modified, then include them in this subcategory. Common examples - include `event.category:process AND event.type:change`, and `event.category:file - AND event.type:change`. You can further distinguish change operations using - the ECS `event.action` field. - - ' + - description: The change event type is used for the subset of events within a category + that indicate that something has changed. If semantics best describe an event + as modified, then include them in this subcategory. Common examples include + `event.category:process AND event.type:change`, and `event.category:file AND + event.type:change`. You can further distinguish change operations using the + ECS `event.action` field. name: change - - description: 'Used primarily with `event.category:network` this value is used - for the subset of network traffic that includes sufficient information for the - event to be included in flow or connection analysis. Events in this subcategory - will contain at least source and destination IP addresses, source and destination + - description: Used primarily with `event.category:network` this value is used for + the subset of network traffic that includes sufficient information for the event + to be included in flow or connection analysis. Events in this subcategory will + contain at least source and destination IP addresses, source and destination TCP/UDP ports, and will usually contain counts of bytes and/or packets transferred. Events in this subcategory may contain unidirectional or bidirectional information, including summary information. Use this subcategory to visualize and analyze @@ -2253,72 +2199,54 @@ event.type: mid-flow reports). You can further distinguish connection events using the ECS `event.action` field, populating with values of your choosing, such as "timeout", or "reset". - - ' name: connection - - description: 'The "creation" event type is used for the subset of events within + - description: The "creation" event type is used for the subset of events within a category that indicate that something was created. A common example is `event.category:file AND event.type:creation`. - - ' name: creation - - description: 'The deletion event type is used for the subset of events within - a category that indicate that something was deleted. A common example is `event.category:file + - description: The deletion event type is used for the subset of events within a + category that indicate that something was deleted. A common example is `event.category:file AND event.type:deletion` to indicate that a file has been deleted. - - ' name: deletion - - description: 'The denied event type is used for the subset of events within a - category that indicate that something was denied. Common examples include `event.category:network + - description: The denied event type is used for the subset of events within a category + that indicate that something was denied. Common examples include `event.category:network AND event.type:denied` (to indicate a network firewall event for which the firewall disposition was to deny the connection) and `event.category:intrusion_detection AND event.type:denied` (to indicate a network intrusion prevention system event for which the IPS disposition was to deny the connection to complete). You can further distinguish denied operations using the ECS `event.action` field, populating with values of your choosing, such as "blocked", "dropped", or "quarantined". - - ' name: denied - - description: 'The end event type is used for the subset of events within a category + - description: The end event type is used for the subset of events within a category that indicate something has ended. A common example is `event.category:process AND event.type:end`. - - ' name: end - - description: 'The error event type is used for the subset of events within a category + - description: The error event type is used for the subset of events within a category that indicate or describe an error. A common example is `event.category:database AND event.type:error`. Note that pipeline errors that occur during the event ingestion process should not use this `event.type` value. Instead, they should use `event.kind:pipeline_error`. - - ' name: error - description: 'The group event type is used for the subset of events within a category that are related to group objects. Common example: `event.category:iam AND event.type:creation AND event.type:group`. You can further distinguish group operations using the - ECS `event.action` field. - - ' + ECS `event.action` field.' name: group - - description: 'The info event type is used for the subset of events within a category - that indicate that they are purely informational, and don''t report a state - change, or any type of action. For example, an initial run of a file integrity - monitoring system (FIM), where an agent reports all files under management, - would fall into the "info" subcategory. Similarly, an event containing a dump - of all currently running processes (as opposed to reporting that a process started/ended) - would fall into the "info" subcategory. An additional common examples is `event.category:intrusion_detection + - description: The info event type is used for the subset of events within a category + that indicate that they are purely informational, and don't report a state change, + or any type of action. For example, an initial run of a file integrity monitoring + system (FIM), where an agent reports all files under management, would fall + into the "info" subcategory. Similarly, an event containing a dump of all currently + running processes (as opposed to reporting that a process started/ended) would + fall into the "info" subcategory. An additional common examples is `event.category:intrusion_detection AND event.type:info`. - - ' name: info - - description: 'The installation event type is used for the subset of events within + - description: The installation event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:installation`. - - ' name: installation - - description: 'The protocol event type is used for the subset of events within - a category that indicate that they contain protocol details or analysis, beyond + - description: The protocol event type is used for the subset of events within a + category that indicate that they contain protocol details or analysis, beyond simply identifying the protocol. Generally, network events that contain specific protocol details will fall into this subcategory. A common example is `event.category:network AND event.type:protocol AND event.type:connection AND event.type:end` (to indicate @@ -2327,8 +2255,6 @@ event.type: indicate the name or id of the protocol should not use the protocol value. Further note that when the protocol subcategory is used, the identified protocol is populated in the ECS `network.protocol` field. - - ' expected_event_types: - access - change @@ -2336,18 +2262,14 @@ event.type: - info - start name: protocol - - description: 'The start event type is used for the subset of events within a category + - description: The start event type is used for the subset of events within a category that indicate something has started. A common example is `event.category:process AND event.type:start`. - - ' name: start - description: 'The user event type is used for the subset of events within a category that are related to user objects. Common example: `event.category:iam AND event.type:deletion AND event.type:user`. You can further distinguish user operations using the - ECS `event.action` field. - - ' + ECS `event.action` field.' name: user dashed_name: event-type description: 'This is one of four ECS Categorization Fields, and indicates the third @@ -2848,10 +2770,7 @@ file.x509.alternative_names: normalize: - array original_fieldset: x509 - short: List of subject alternative names (SAN). Name types vary by certificate authority - and certificate type but commonly contain IP addresses, DNS names (and wildcards), - and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword file.x509.issuer.common_name: dashed_name: file-x509-issuer-common-name @@ -3028,15 +2947,12 @@ file.x509.serial_number: name: serial_number normalize: [] original_fieldset: x509 - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword file.x509.signature_algorithm: dashed_name: file-x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: file.x509.signature_algorithm ignore_above: 1024 @@ -3044,8 +2960,7 @@ file.x509.signature_algorithm: name: signature_algorithm normalize: [] original_fieldset: x509 - short: Identifier for certificate signature algorithm. Recommend using names found - in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword file.x509.subject.common_name: dashed_name: file-x509-subject-common-name @@ -3843,7 +3758,6 @@ log.syslog: level: extended name: syslog normalize: [] - object_type: keyword short: Syslog metadata type: object log.syslog.facility.code: @@ -4026,7 +3940,6 @@ network.inner: level: extended name: inner normalize: [] - object_type: keyword short: Inner VLAN tag information type: object network.inner.vlan.id: @@ -4156,7 +4069,6 @@ observer.egress: level: extended name: egress normalize: [] - object_type: keyword short: Object field for egress information type: object observer.egress.interface.alias: @@ -4354,7 +4266,6 @@ observer.ingress: level: extended name: ingress normalize: [] - object_type: keyword short: Object field for ingress information type: object observer.ingress.interface.alias: @@ -5919,8 +5830,7 @@ server.as.number: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system number - (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long server.as.organization.name: dashed_name: server-as-organization-name @@ -6415,8 +6325,7 @@ source.as.number: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system number - (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long source.as.organization.name: dashed_name: source-as-organization-name @@ -6907,9 +6816,7 @@ tls.client.certificate: level: extended name: client.certificate normalize: [] - short: PEM-encoded stand-alone certificate offered by the client. This is usually - mutually-exclusive of `client.certificate_chain` since this value also exists - in that list. + short: PEM-encoded stand-alone certificate offered by the client. type: keyword tls.client.certificate_chain: dashed_name: tls-client-certificate-chain @@ -6926,8 +6833,7 @@ tls.client.certificate_chain: normalize: - array short: Array of PEM-encoded certificates that make up the certificate chain offered - by the client. This is usually mutually-exclusive of `client.certificate` since - that value should be the first certificate in the chain. + by the client. type: keyword tls.client.hash.md5: dashed_name: tls-client-hash-md5 @@ -6941,8 +6847,7 @@ tls.client.hash.md5: name: client.hash.md5 normalize: [] short: Certificate fingerprint using the MD5 digest of DER-encoded version of certificate - offered by the client. For consistency with other hash values, this value should - be formatted as an uppercase hash. + offered by the client. type: keyword tls.client.hash.sha1: dashed_name: tls-client-hash-sha1 @@ -6956,8 +6861,7 @@ tls.client.hash.sha1: name: client.hash.sha1 normalize: [] short: Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate - offered by the client. For consistency with other hash values, this value should - be formatted as an uppercase hash. + offered by the client. type: keyword tls.client.hash.sha256: dashed_name: tls-client-hash-sha256 @@ -6971,8 +6875,7 @@ tls.client.hash.sha256: name: client.hash.sha256 normalize: [] short: Certificate fingerprint using the SHA256 digest of DER-encoded version of - certificate offered by the client. For consistency with other hash values, this - value should be formatted as an uppercase hash. + certificate offered by the client. type: keyword tls.client.issuer: dashed_name: tls-client-issuer @@ -7023,17 +6926,15 @@ tls.client.not_before: tls.client.server_name: dashed_name: tls-client-server-name description: Also called an SNI, this tells the server which hostname to which the - client is attempting to connect. When this value is available, it should get copied - to `destination.domain`. + client is attempting to connect to. When this value is available, it should get + copied to `destination.domain`. example: www.elastic.co flat_name: tls.client.server_name ignore_above: 1024 level: extended name: client.server_name normalize: [] - short: Also called an SNI, this tells the server which hostname to which the client - is attempting to connect. When this value is available, it should get copied to - `destination.domain`. + short: Hostname the client is trying to connect to. Also called the SNI. type: keyword tls.client.subject: dashed_name: tls-client-subject @@ -7075,10 +6976,7 @@ tls.client.x509.alternative_names: normalize: - array original_fieldset: x509 - short: List of subject alternative names (SAN). Name types vary by certificate authority - and certificate type but commonly contain IP addresses, DNS names (and wildcards), - and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword tls.client.x509.issuer.common_name: dashed_name: tls-client-x509-issuer-common-name @@ -7255,15 +7153,12 @@ tls.client.x509.serial_number: name: serial_number normalize: [] original_fieldset: x509 - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword tls.client.x509.signature_algorithm: dashed_name: tls-client-x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: tls.client.x509.signature_algorithm ignore_above: 1024 @@ -7271,8 +7166,7 @@ tls.client.x509.signature_algorithm: name: signature_algorithm normalize: [] original_fieldset: x509 - short: Identifier for certificate signature algorithm. Recommend using names found - in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword tls.client.x509.subject.common_name: dashed_name: tls-client-x509-subject-common-name @@ -7408,9 +7302,7 @@ tls.next_protocol: level: extended name: next_protocol normalize: [] - short: String indicating the protocol being tunneled. Per the values in the IANA - registry (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), - this string should be lower case. + short: String indicating the protocol being tunneled. type: keyword tls.resumed: dashed_name: tls-resumed @@ -7434,9 +7326,7 @@ tls.server.certificate: level: extended name: server.certificate normalize: [] - short: PEM-encoded stand-alone certificate offered by the server. This is usually - mutually-exclusive of `server.certificate_chain` since this value also exists - in that list. + short: PEM-encoded stand-alone certificate offered by the server. type: keyword tls.server.certificate_chain: dashed_name: tls-server-certificate-chain @@ -7453,8 +7343,7 @@ tls.server.certificate_chain: normalize: - array short: Array of PEM-encoded certificates that make up the certificate chain offered - by the server. This is usually mutually-exclusive of `server.certificate` since - that value should be the first certificate in the chain. + by the server. type: keyword tls.server.hash.md5: dashed_name: tls-server-hash-md5 @@ -7468,8 +7357,7 @@ tls.server.hash.md5: name: server.hash.md5 normalize: [] short: Certificate fingerprint using the MD5 digest of DER-encoded version of certificate - offered by the server. For consistency with other hash values, this value should - be formatted as an uppercase hash. + offered by the server. type: keyword tls.server.hash.sha1: dashed_name: tls-server-hash-sha1 @@ -7483,8 +7371,7 @@ tls.server.hash.sha1: name: server.hash.sha1 normalize: [] short: Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate - offered by the server. For consistency with other hash values, this value should - be formatted as an uppercase hash. + offered by the server. type: keyword tls.server.hash.sha256: dashed_name: tls-server-hash-sha256 @@ -7498,8 +7385,7 @@ tls.server.hash.sha256: name: server.hash.sha256 normalize: [] short: Certificate fingerprint using the SHA256 digest of DER-encoded version of - certificate offered by the server. For consistency with other hash values, this - value should be formatted as an uppercase hash. + certificate offered by the server. type: keyword tls.server.issuer: dashed_name: tls-server-issuer @@ -7569,10 +7455,7 @@ tls.server.x509.alternative_names: normalize: - array original_fieldset: x509 - short: List of subject alternative names (SAN). Name types vary by certificate authority - and certificate type but commonly contain IP addresses, DNS names (and wildcards), - and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword tls.server.x509.issuer.common_name: dashed_name: tls-server-x509-issuer-common-name @@ -7749,15 +7632,12 @@ tls.server.x509.serial_number: name: serial_number normalize: [] original_fieldset: x509 - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword tls.server.x509.signature_algorithm: dashed_name: tls-server-x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: tls.server.x509.signature_algorithm ignore_above: 1024 @@ -7765,8 +7645,7 @@ tls.server.x509.signature_algorithm: name: signature_algorithm normalize: [] original_fieldset: x509 - short: Identifier for certificate signature algorithm. Recommend using names found - in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword tls.server.x509.subject.common_name: dashed_name: tls-server-x509-subject-common-name diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 660f8e93e9..0d6e383225 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -116,8 +116,7 @@ as: level: extended name: number normalize: [] - short: Unique number allocated to the autonomous system. The autonomous system - number (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long as.organization.name: dashed_name: as-organization-name @@ -157,11 +156,11 @@ as: title: Autonomous System type: group base: - description: The `base` field set contains all fields which are on the top level. - These fields are common across all types of events. + description: The `base` field set contains all fields which are at the root of the + events. These fields are common across all types of events. fields: '@timestamp': - dashed_name: '@timestamp' + dashed_name: -timestamp description: 'Date/time when the event originated. This is the date/time extracted from the event, typically representing when @@ -228,7 +227,7 @@ base: name: base prefix: '' root: true - short: All fields defined directly at the top level + short: All fields defined directly at the root of the events. title: Base type: group client: @@ -273,8 +272,7 @@ client: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system - number (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long client.as.organization.name: dashed_name: client-as-organization-name @@ -975,8 +973,7 @@ destination: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system - number (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long destination.as.organization.name: dashed_name: destination-as-organization-name @@ -1636,7 +1633,6 @@ dns: name: answers normalize: - array - object_type: keyword short: Array of DNS answers. type: object dns.answers.class: @@ -1689,8 +1685,7 @@ dns: name: answers.ttl normalize: [] short: The time interval in seconds that this resource record may be cached - before it should be discarded. Zero values mean that the data should not be - cached. + before it should be discarded. type: long dns.answers.type: dashed_name: dns-answers-type @@ -1744,7 +1739,6 @@ dns: name: op_code normalize: [] short: The DNS operation code that specifies the kind of query in the message. - This value is set by the originator of a query and copied into the response. type: keyword dns.question.class: dashed_name: dns-question-class @@ -2012,25 +2006,21 @@ event: type: keyword event.category: allowed_values: - - description: 'Events in this category are related to the challenge and response + - description: Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows event logs and ssh logs. Visualize and analyze events in this category to look for failed logins, and other authentication-related activity. - - ' expected_event_types: - start - end - info name: authentication - - description: 'The database category denotes events and metrics relating to + - description: The database category denotes events and metrics relating to a data storage and retrieval system. Note that use of this category is not limited to relational database systems. Examples include event logs from MS SQL, MySQL, Elasticsearch, MongoDB, etc. Use this category to visualize and analyze database activity such as accesses and changes. - - ' expected_event_types: - access - change @@ -2042,22 +2032,18 @@ event: extensions, kernel modules, etc. Use events and metrics in this category to visualize and analyze driver-related - activity and status on hosts. - - ' + activity and status on hosts.' expected_event_types: - change - end - info - start name: driver - - description: 'Relating to a set of information that has been created on, or + - description: Relating to a set of information that has been created on, or has existed on a filesystem. Use this category of events to visualize and analyze the creation, access, and deletions of files. Events in this category can come from both host-based and network-based sources. An example source of a network-based detection of a file transfer would be the Zeek file.log. - - ' expected_event_types: - change - creation @@ -2072,9 +2058,7 @@ event: also be seen from within, such as "start" or "end". Note that this category is for information about hosts themselves; it is - not meant to capture activity "happening on a host". - - ' + not meant to capture activity "happening on a host".' expected_event_types: - access - change @@ -2082,11 +2066,9 @@ event: - info - start name: host - - description: 'Identity and access management (IAM) events relating to users, + - description: Identity and access management (IAM) events relating to users, groups, and administration. Use this category to visualize and analyze IAM-related logs and data from active directory, LDAP, Okta, Duo, and other IAM systems. - - ' expected_event_types: - admin - change @@ -2096,35 +2078,29 @@ event: - info - user name: iam - - description: 'Relating to intrusion detections from IDS/IPS systems and functions, + - description: Relating to intrusion detections from IDS/IPS systems and functions, both network and host-based. Use this category to visualize and analyze intrusion detection alerts from systems such as Snort, Suricata, and Palo Alto threat detections. - - ' expected_event_types: - allowed - denied - info name: intrusion_detection - - description: 'Malware detection events and alerts. Use this category to visualize + - description: Malware detection events and alerts. Use this category to visualize and analyze malware detections from EDR/EPP systems such as Elastic Endpoint Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems such as Suricata, or other sources of malware-related events such as Palo Alto Networks threat logs and Wildfire logs. - - ' expected_event_types: - info name: malware - - description: 'Relating to all network activity, including network connection + - description: Relating to all network activity, including network connection lifecycle, network traffic, and essentially any event that includes an IP address. Many events containing decoded network protocol transactions fit into this category. Use events in this category to visualize or analyze counts of network ports, protocols, addresses, geolocation information, etc. - - ' expected_event_types: - access - allowed @@ -2135,12 +2111,10 @@ event: - protocol - start name: network - - description: 'Relating to software packages installed on hosts. Use this category + - description: Relating to software packages installed on hosts. Use this category to visualize and analyze inventory of software installed on various hosts, or to determine host vulnerability in the absence of vulnerability scan data. - - ' expected_event_types: - access - change @@ -2149,10 +2123,8 @@ event: - installation - start name: package - - description: 'Use this category of events to visualize and analyze process-specific + - description: Use this category of events to visualize and analyze process-specific information such as lifecycle events or process ancestry. - - ' expected_event_types: - access - change @@ -2163,9 +2135,7 @@ event: - description: 'Relating to web server access. Use this category to create a dashboard of web server/proxy activity from apache, IIS, nginx web servers, etc. Note: events from network observers such as Zeek http log may also - be included in this category. - - ' + be included in this category.' expected_event_types: - access - error @@ -2320,14 +2290,10 @@ event: `event.kind:alert` is often populated for events coming from firewalls, intrusion detection systems, endpoint detection and response systems, and - so on. - - ' + so on.' name: alert - - description: 'This value is the most general and most common value for this + - description: This value is the most general and most common value for this field. It is used to represent events that indicate that something happened. - - ' name: event - description: 'This value is used to indicate that this event describes a numeric measurement taken at given point in time. @@ -2336,9 +2302,7 @@ event: Metric events are often collected on a predictable frequency, such as once every few seconds, or once a minute, but can also be used to describe ad-hoc - numeric metric queries. - - ' + numeric metric queries.' name: metric - description: 'The state value is similar to metric, indicating that this event describes a measurement taken at given point in time, except that the measurement @@ -2357,15 +2321,11 @@ event: State events are often collected on a predictable frequency, such as once every few seconds, once a minute, once an hour, or once a day, but can also - be used to describe ad-hoc state queries. - - ' + be used to describe ad-hoc state queries.' name: state - - description: 'This value indicates that an error occurred during the ingestion + - description: This value indicates that an error occurred during the ingestion of this event, and that event data may be missing, inconsistent, or incorrect. `event.kind:pipeline_error` is often associated with parsing errors. - - ' name: pipeline_error - description: 'This value is used by the Elastic SIEM app to denote an Elasticsearch document that was created by a SIEM detection engine rule. @@ -2374,9 +2334,7 @@ event: happened and should be investigated. Usage of this value is reserved, and pipelines should not populate `event.kind` - with the value "signal". - - ' + with the value "signal".' name: signal dashed_name: event-kind description: 'This is one of four ECS Categorization Fields, and indicates the @@ -2432,27 +2390,21 @@ event: type: keyword event.outcome: allowed_values: - - description: 'Indicates that this event describes a failed result. A common + - description: Indicates that this event describes a failed result. A common example is `event.category:file AND event.type:access AND event.outcome:failure` to indicate that a file access was attempted, but was not successful. - - ' name: failure - - description: 'Indicates that this event describes a successful result. A common + - description: Indicates that this event describes a successful result. A common example is `event.category:file AND event.type:create AND event.outcome:success` to indicate that a file was successfully created. - - ' name: success - - description: 'Indicates that this event describes only an attempt for which + - description: Indicates that this event describes only an attempt for which the result is unknown from the perspective of the event producer. For example, if the event contains information only about the request side of a transaction that results in a response, populating `event.outcome:unknown` in the request event is appropriate. The unknown value should not be used when an outcome - doesn''t make logical sense for the event. In such cases `event.outcome` + doesn't make logical sense for the event. In such cases `event.outcome` should not be populated. - - ' name: unknown dashed_name: event-outcome description: 'This is one of four ECS Categorization Fields, and indicates the @@ -2597,14 +2549,12 @@ event: type: keyword event.type: allowed_values: - - description: 'The access event type is used for the subset of events within + - description: The access event type is used for the subset of events within a category that indicate that something was accessed. Common examples include `event.category:database AND event.type:access`, or `event.category:file AND event.type:access`. Note for file access, both directory listings and file opens should be included in this subcategory. You can further distinguish access operations using the ECS `event.action` field. - - ' name: access - description: 'The admin event type is used for the subset of events within a category that are related to admin objects. For example, administrative @@ -2613,11 +2563,9 @@ event: discrete forests in Active Directory) would fall into this subcategory. Common example: `event.category:iam AND event.type:change AND event.type:admin`. You can further distinguish admin operations using the ECS `event.action` - field. - - ' + field.' name: admin - - description: 'The allowed event type is used for the subset of events within + - description: The allowed event type is used for the subset of events within a category that indicate that something was allowed. Common examples include `event.category:network AND event.type:connection AND event.type:allowed` (to indicate a network firewall event for which the firewall disposition @@ -2627,19 +2575,15 @@ event: You can further distinguish allowed operations using the ECS `event.action` field, populating with values of your choosing, such as "allow", "detect", or "pass". - - ' name: allowed - - description: 'The change event type is used for the subset of events within + - description: The change event type is used for the subset of events within a category that indicate that something has changed. If semantics best describe an event as modified, then include them in this subcategory. Common examples include `event.category:process AND event.type:change`, and `event.category:file AND event.type:change`. You can further distinguish change operations using the ECS `event.action` field. - - ' name: change - - description: 'Used primarily with `event.category:network` this value is used + - description: Used primarily with `event.category:network` this value is used for the subset of network traffic that includes sufficient information for the event to be included in flow or connection analysis. Events in this subcategory will contain at least source and destination IP addresses, source @@ -2654,23 +2598,17 @@ event: (to view or analyze all completed network connections, ignoring mid-flow reports). You can further distinguish connection events using the ECS `event.action` field, populating with values of your choosing, such as "timeout", or "reset". - - ' name: connection - - description: 'The "creation" event type is used for the subset of events within + - description: The "creation" event type is used for the subset of events within a category that indicate that something was created. A common example is `event.category:file AND event.type:creation`. - - ' name: creation - - description: 'The deletion event type is used for the subset of events within + - description: The deletion event type is used for the subset of events within a category that indicate that something was deleted. A common example is `event.category:file AND event.type:deletion` to indicate that a file has been deleted. - - ' name: deletion - - description: 'The denied event type is used for the subset of events within + - description: The denied event type is used for the subset of events within a category that indicate that something was denied. Common examples include `event.category:network AND event.type:denied` (to indicate a network firewall event for which the firewall disposition was to deny the connection) and @@ -2679,49 +2617,37 @@ event: was to deny the connection to complete). You can further distinguish denied operations using the ECS `event.action` field, populating with values of your choosing, such as "blocked", "dropped", or "quarantined". - - ' name: denied - - description: 'The end event type is used for the subset of events within a + - description: The end event type is used for the subset of events within a category that indicate something has ended. A common example is `event.category:process AND event.type:end`. - - ' name: end - - description: 'The error event type is used for the subset of events within + - description: The error event type is used for the subset of events within a category that indicate or describe an error. A common example is `event.category:database AND event.type:error`. Note that pipeline errors that occur during the event ingestion process should not use this `event.type` value. Instead, they should use `event.kind:pipeline_error`. - - ' name: error - description: 'The group event type is used for the subset of events within a category that are related to group objects. Common example: `event.category:iam AND event.type:creation AND event.type:group`. You can further distinguish - group operations using the ECS `event.action` field. - - ' + group operations using the ECS `event.action` field.' name: group - - description: 'The info event type is used for the subset of events within - a category that indicate that they are purely informational, and don''t - report a state change, or any type of action. For example, an initial run - of a file integrity monitoring system (FIM), where an agent reports all - files under management, would fall into the "info" subcategory. Similarly, - an event containing a dump of all currently running processes (as opposed - to reporting that a process started/ended) would fall into the "info" subcategory. + - description: The info event type is used for the subset of events within a + category that indicate that they are purely informational, and don't report + a state change, or any type of action. For example, an initial run of a + file integrity monitoring system (FIM), where an agent reports all files + under management, would fall into the "info" subcategory. Similarly, an + event containing a dump of all currently running processes (as opposed to + reporting that a process started/ended) would fall into the "info" subcategory. An additional common examples is `event.category:intrusion_detection AND event.type:info`. - - ' name: info - - description: 'The installation event type is used for the subset of events + - description: The installation event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:installation`. - - ' name: installation - - description: 'The protocol event type is used for the subset of events within + - description: The protocol event type is used for the subset of events within a category that indicate that they contain protocol details or analysis, beyond simply identifying the protocol. Generally, network events that contain specific protocol details will fall into this subcategory. A common example @@ -2732,8 +2658,6 @@ event: should not use the protocol value. Further note that when the protocol subcategory is used, the identified protocol is populated in the ECS `network.protocol` field. - - ' expected_event_types: - access - change @@ -2741,18 +2665,14 @@ event: - info - start name: protocol - - description: 'The start event type is used for the subset of events within + - description: The start event type is used for the subset of events within a category that indicate something has started. A common example is `event.category:process AND event.type:start`. - - ' name: start - description: 'The user event type is used for the subset of events within a category that are related to user objects. Common example: `event.category:iam AND event.type:deletion AND event.type:user`. You can further distinguish - user operations using the ECS `event.action` field. - - ' + user operations using the ECS `event.action` field.' name: user dashed_name: event-type description: 'This is one of four ECS Categorization Fields, and indicates the @@ -3268,10 +3188,7 @@ file: normalize: - array original_fieldset: x509 - short: List of subject alternative names (SAN). Name types vary by certificate - authority and certificate type but commonly contain IP addresses, DNS names - (and wildcards), and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword file.x509.issuer.common_name: dashed_name: file-x509-issuer-common-name @@ -3448,15 +3365,12 @@ file: name: serial_number normalize: [] original_fieldset: x509 - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword file.x509.signature_algorithm: dashed_name: file-x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: file.x509.signature_algorithm ignore_above: 1024 @@ -3464,8 +3378,7 @@ file: name: signature_algorithm normalize: [] original_fieldset: x509 - short: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword file.x509.subject.common_name: dashed_name: file-x509-subject-common-name @@ -3588,14 +3501,7 @@ file: short: These fields contain Windows Portable Executable (PE) metadata. - full: file.x509 schema_name: x509 - short: 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`). + short: These fields contain x509 certificate metadata. short: Fields describing files. title: File type: group @@ -4594,7 +4500,6 @@ log: level: extended name: syslog normalize: [] - object_type: keyword short: Syslog metadata type: object log.syslog.facility.code: @@ -4777,7 +4682,6 @@ network: level: extended name: inner normalize: [] - object_type: keyword short: Inner VLAN tag information type: object network.inner.vlan.id: @@ -4937,7 +4841,6 @@ observer: level: extended name: egress normalize: [] - object_type: keyword short: Object field for egress information type: object observer.egress.interface.alias: @@ -5136,7 +5039,6 @@ observer: level: extended name: ingress normalize: [] - object_type: keyword short: Object field for ingress information type: object observer.ingress.interface.alias: @@ -7057,8 +6959,7 @@ server: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system - number (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long server.as.organization.name: dashed_name: server-as-organization-name @@ -7591,8 +7492,7 @@ source: name: number normalize: [] original_fieldset: as - short: Unique number allocated to the autonomous system. The autonomous system - number (ASN) uniquely identifies each network on the Internet. + short: Unique number allocated to the autonomous system. type: long source.as.organization.name: dashed_name: source-as-organization-name @@ -8111,9 +8011,7 @@ tls: level: extended name: client.certificate normalize: [] - short: PEM-encoded stand-alone certificate offered by the client. This is usually - mutually-exclusive of `client.certificate_chain` since this value also exists - in that list. + short: PEM-encoded stand-alone certificate offered by the client. type: keyword tls.client.certificate_chain: dashed_name: tls-client-certificate-chain @@ -8130,8 +8028,7 @@ tls: normalize: - array short: Array of PEM-encoded certificates that make up the certificate chain - offered by the client. This is usually mutually-exclusive of `client.certificate` - since that value should be the first certificate in the chain. + offered by the client. type: keyword tls.client.hash.md5: dashed_name: tls-client-hash-md5 @@ -8145,8 +8042,7 @@ tls: name: client.hash.md5 normalize: [] short: Certificate fingerprint using the MD5 digest of DER-encoded version of - certificate offered by the client. For consistency with other hash values, - this value should be formatted as an uppercase hash. + certificate offered by the client. type: keyword tls.client.hash.sha1: dashed_name: tls-client-hash-sha1 @@ -8160,8 +8056,7 @@ tls: name: client.hash.sha1 normalize: [] short: Certificate fingerprint using the SHA1 digest of DER-encoded version - of certificate offered by the client. For consistency with other hash values, - this value should be formatted as an uppercase hash. + of certificate offered by the client. type: keyword tls.client.hash.sha256: dashed_name: tls-client-hash-sha256 @@ -8175,8 +8070,7 @@ tls: name: client.hash.sha256 normalize: [] short: Certificate fingerprint using the SHA256 digest of DER-encoded version - of certificate offered by the client. For consistency with other hash values, - this value should be formatted as an uppercase hash. + of certificate offered by the client. type: keyword tls.client.issuer: dashed_name: tls-client-issuer @@ -8229,7 +8123,7 @@ tls: tls.client.server_name: dashed_name: tls-client-server-name description: Also called an SNI, this tells the server which hostname to which - the client is attempting to connect. When this value is available, it should + the client is attempting to connect to. When this value is available, it should get copied to `destination.domain`. example: www.elastic.co flat_name: tls.client.server_name @@ -8237,9 +8131,7 @@ tls: level: extended name: client.server_name normalize: [] - short: Also called an SNI, this tells the server which hostname to which the - client is attempting to connect. When this value is available, it should get - copied to `destination.domain`. + short: Hostname the client is trying to connect to. Also called the SNI. type: keyword tls.client.subject: dashed_name: tls-client-subject @@ -8282,10 +8174,7 @@ tls: normalize: - array original_fieldset: x509 - short: List of subject alternative names (SAN). Name types vary by certificate - authority and certificate type but commonly contain IP addresses, DNS names - (and wildcards), and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword tls.client.x509.issuer.common_name: dashed_name: tls-client-x509-issuer-common-name @@ -8462,15 +8351,12 @@ tls: name: serial_number normalize: [] original_fieldset: x509 - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword tls.client.x509.signature_algorithm: dashed_name: tls-client-x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: tls.client.x509.signature_algorithm ignore_above: 1024 @@ -8478,8 +8364,7 @@ tls: name: signature_algorithm normalize: [] original_fieldset: x509 - short: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword tls.client.x509.subject.common_name: dashed_name: tls-client-x509-subject-common-name @@ -8615,9 +8500,7 @@ tls: level: extended name: next_protocol normalize: [] - short: String indicating the protocol being tunneled. Per the values in the - IANA registry (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), - this string should be lower case. + short: String indicating the protocol being tunneled. type: keyword tls.resumed: dashed_name: tls-resumed @@ -8641,9 +8524,7 @@ tls: level: extended name: server.certificate normalize: [] - short: PEM-encoded stand-alone certificate offered by the server. This is usually - mutually-exclusive of `server.certificate_chain` since this value also exists - in that list. + short: PEM-encoded stand-alone certificate offered by the server. type: keyword tls.server.certificate_chain: dashed_name: tls-server-certificate-chain @@ -8660,8 +8541,7 @@ tls: normalize: - array short: Array of PEM-encoded certificates that make up the certificate chain - offered by the server. This is usually mutually-exclusive of `server.certificate` - since that value should be the first certificate in the chain. + offered by the server. type: keyword tls.server.hash.md5: dashed_name: tls-server-hash-md5 @@ -8675,8 +8555,7 @@ tls: name: server.hash.md5 normalize: [] short: Certificate fingerprint using the MD5 digest of DER-encoded version of - certificate offered by the server. For consistency with other hash values, - this value should be formatted as an uppercase hash. + certificate offered by the server. type: keyword tls.server.hash.sha1: dashed_name: tls-server-hash-sha1 @@ -8690,8 +8569,7 @@ tls: name: server.hash.sha1 normalize: [] short: Certificate fingerprint using the SHA1 digest of DER-encoded version - of certificate offered by the server. For consistency with other hash values, - this value should be formatted as an uppercase hash. + of certificate offered by the server. type: keyword tls.server.hash.sha256: dashed_name: tls-server-hash-sha256 @@ -8705,8 +8583,7 @@ tls: name: server.hash.sha256 normalize: [] short: Certificate fingerprint using the SHA256 digest of DER-encoded version - of certificate offered by the server. For consistency with other hash values, - this value should be formatted as an uppercase hash. + of certificate offered by the server. type: keyword tls.server.issuer: dashed_name: tls-server-issuer @@ -8779,10 +8656,7 @@ tls: normalize: - array original_fieldset: x509 - short: List of subject alternative names (SAN). Name types vary by certificate - authority and certificate type but commonly contain IP addresses, DNS names - (and wildcards), and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword tls.server.x509.issuer.common_name: dashed_name: tls-server-x509-issuer-common-name @@ -8959,15 +8833,12 @@ tls: name: serial_number normalize: [] original_fieldset: x509 - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword tls.server.x509.signature_algorithm: dashed_name: tls-server-x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: tls.server.x509.signature_algorithm ignore_above: 1024 @@ -8975,8 +8846,7 @@ tls: name: signature_algorithm normalize: [] original_fieldset: x509 - short: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword tls.server.x509.subject.common_name: dashed_name: tls-server-x509-subject-common-name @@ -9110,24 +8980,10 @@ tls: reused_here: - full: tls.client.x509 schema_name: x509 - short: 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`). + short: These fields contain x509 certificate metadata. - full: tls.server.x509 schema_name: x509 - short: 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`). + short: These fields contain x509 certificate metadata. short: Fields describing a TLS connection. title: TLS type: group @@ -9936,10 +9792,7 @@ x509: name: alternative_names normalize: - array - short: List of subject alternative names (SAN). Name types vary by certificate - authority and certificate type but commonly contain IP addresses, DNS names - (and wildcards), and email addresses. - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). type: keyword x509.issuer.common_name: dashed_name: x509-issuer-common-name @@ -10102,23 +9955,19 @@ x509: level: extended name: serial_number normalize: [] - short: Unique serial number issued by the certificate authority. For consistency, - if this value is alphanumeric, it should be formatted without colons and uppercase - characters. - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. type: keyword x509.signature_algorithm: dashed_name: x509-signature-algorithm - description: Identifier for certificate signature algorithm. Recommend using - names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + description: Identifier for certificate signature algorithm. We recommend using + names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA flat_name: x509.signature_algorithm ignore_above: 1024 level: extended name: signature_algorithm normalize: [] - short: Identifier for certificate signature algorithm. Recommend using names - found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. type: keyword x509.subject.common_name: dashed_name: x509-subject-common-name @@ -10228,14 +10077,6 @@ x509: at: tls.server full: tls.server.x509 top_level: false - short: 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`). - short_description: These fields contain x509 certificate metadata. + short: These fields contain x509 certificate metadata. title: x509 Certificate type: group diff --git a/schemas/as.yml b/schemas/as.yml index 8654685680..952d7febeb 100644 --- a/schemas/as.yml +++ b/schemas/as.yml @@ -21,6 +21,7 @@ - name: number level: extended type: long + short: Unique number allocated to the autonomous system. description: > Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. diff --git a/schemas/base.yml b/schemas/base.yml index 99e301cfe8..1d1fc333f1 100644 --- a/schemas/base.yml +++ b/schemas/base.yml @@ -3,9 +3,9 @@ root: true title: Base group: 1 - short: All fields defined directly at the top level + short: All fields defined directly at the root of the events. description: > - The `base` field set contains all fields which are on the top level. + The `base` field set contains all fields which are at the root of the events. These fields are common across all types of events. type: group fields: diff --git a/schemas/dns.yml b/schemas/dns.yml index 6fe8bad326..f5e4b9e6e3 100644 --- a/schemas/dns.yml +++ b/schemas/dns.yml @@ -39,6 +39,7 @@ - name: op_code level: extended type: keyword + short: The DNS operation code that specifies the kind of query in the message. description: > The DNS operation code that specifies the kind of query in the message. This value is set by the originator of a query and copied into the @@ -174,6 +175,8 @@ - name: answers.ttl level: extended type: long + short: The time interval in seconds that this resource record may be cached + before it should be discarded. description: > The time interval in seconds that this resource record may be cached before it should be discarded. Zero values mean that the data should diff --git a/schemas/tls.yml b/schemas/tls.yml index 4b2059e120..b9dea030d8 100644 --- a/schemas/tls.yml +++ b/schemas/tls.yml @@ -47,6 +47,7 @@ - name: next_protocol type: keyword level: extended + short: String indicating the protocol being tunneled. description: > String indicating the protocol being tunneled. Per the values in the IANA registry (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), @@ -62,9 +63,10 @@ - name: client.server_name type: keyword level: extended + short: Hostname the client is trying to connect to. Also called the SNI. description: > - Also called an SNI, this tells the server which hostname to which the client is attempting to connect. When - this value is available, it should get copied to `destination.domain`. + Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. + When this value is available, it should get copied to `destination.domain`. example: "www.elastic.co" - name: client.supported_ciphers @@ -102,6 +104,7 @@ - name: client.certificate_chain type: keyword level: extended + short: Array of PEM-encoded certificates that make up the certificate chain offered by the client. description: > Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate @@ -113,6 +116,7 @@ - name: client.certificate type: keyword level: extended + short: PEM-encoded stand-alone certificate offered by the client. description: > PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. @@ -121,6 +125,7 @@ - name: client.hash.md5 type: keyword level: extended + short: Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. description: > Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. @@ -129,6 +134,8 @@ - name: client.hash.sha1 type: keyword level: extended + short: > + Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. description: > Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. @@ -137,6 +144,7 @@ - name: client.hash.sha256 type: keyword level: extended + short: Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. description: > Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. @@ -175,6 +183,7 @@ - name: server.certificate_chain type: keyword level: extended + short: Array of PEM-encoded certificates that make up the certificate chain offered by the server. description: > Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate @@ -186,6 +195,7 @@ - name: server.certificate type: keyword level: extended + short: PEM-encoded stand-alone certificate offered by the server. description: > PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. @@ -194,6 +204,7 @@ - name: server.hash.md5 type: keyword level: extended + short: Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. description: > Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. @@ -202,6 +213,7 @@ - name: server.hash.sha1 type: keyword level: extended + short: Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. description: > Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. @@ -210,6 +222,7 @@ - name: server.hash.sha256 type: keyword level: extended + short: Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. description: > Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. diff --git a/schemas/x509.yml b/schemas/x509.yml index 07571747a6..397573d536 100644 --- a/schemas/x509.yml +++ b/schemas/x509.yml @@ -2,7 +2,7 @@ - name: x509 title: x509 Certificate group: 2 - short_description: These fields contain x509 certificate metadata. + short: These fields contain x509 certificate metadata. 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. @@ -27,7 +27,7 @@ - name: serial_number level: extended type: keyword - short_description: Unique serial number issued by the certificate authority. + short: Unique serial number issued by the certificate authority. description: > Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. @@ -90,7 +90,11 @@ - name: signature_algorithm level: extended type: keyword - description: Identifier for certificate signature algorithm. Recommend using names found in Go Lang Crypto library (See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353). + short: Identifier for certificate signature algorithm. + description: > + Identifier for certificate signature algorithm. + We recommend using names found in Go Lang Crypto library. + See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. example: SHA256-RSA - name: not_before @@ -188,6 +192,6 @@ type: keyword normalize: - array - short_description: List of subject alternative names (SAN) + short: List of subject alternative names (SAN). description: List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. example: "*.elastic.co" diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py index 706cda8b72..c25d7b8162 100644 --- a/scripts/generators/asciidoc_fields.py +++ b/scripts/generators/asciidoc_fields.py @@ -49,8 +49,8 @@ def render_template(template_name, **context): return template.render(**context) -def save_asciidoc(file, text): - with open(file, "w") as outfile: +def save_asciidoc(f, text): + with open(f, "w") as outfile: outfile.write(text) @@ -66,6 +66,7 @@ def page_field_index(nested, ecs_version): # Field Details Page + def page_field_details(nested): page_text = '' for fieldset in ecs_helpers.dict_sorted_by_keys(nested, ['group', 'name']): @@ -184,14 +185,10 @@ def render_fieldset_reuses_text(fieldset): section_name, ', '.join(rendered_fields)) if 'top_level' in fieldset['reusable'] and fieldset['reusable']['top_level']: - # TODO rewording kept for follow-up PR to simplify initial rewrite PR - # template = "Note also that the `{}` fields may be used directly at the root of the events.\n\n" - template = "Note also that the `{}` fields may be used directly at the top level.\n\n" + template = "Note also that the `{}` fields may be used directly at the root of the events.\n\n" else: template = "Note also that the `{}` fields are not expected to " + \ - "be used directly at the top level.\n\n" - # TODO rewording kept for follow-up PR to simplify initial rewrite PR - # "be used directly at the root of the events.\n\n" + "be used directly at the root of the events.\n\n" text += template.format(section_name) return text diff --git a/scripts/schema/cleaner.py b/scripts/schema/cleaner.py index ef56966d36..ec48598bea 100644 --- a/scripts/schema/cleaner.py +++ b/scripts/schema/cleaner.py @@ -118,10 +118,9 @@ def field_cleanup(field): if ecs_helpers.is_intermediate(field): return ecs_helpers.dict_clean_string_values(field['field_details']) - # TODO Temporarily commented out to simplify initial rewrite review - # if 'allowed_values' in field['field_details']: - # for allowed_value in field['field_details']['allowed_values']: - # ecs_helpers.dict_clean_string_values(allowed_value) + if 'allowed_values' in field['field_details']: + for allowed_value in field['field_details']['allowed_values']: + ecs_helpers.dict_clean_string_values(allowed_value) field_defaults(field) field_assertions_and_warnings(field) @@ -129,9 +128,6 @@ def field_cleanup(field): def field_defaults(field): field['field_details'].setdefault('short', field['field_details']['description']) field['field_details'].setdefault('normalize', []) - # TODO Temporarily re-adding object_type for initial rewrite review. I think this should go away. - if 'object' == field['field_details']['type']: - field['field_details'].setdefault('object_type', 'keyword') field_or_multi_field_datatype_defaults(field['field_details']) if 'multi_fields' in field['field_details']: for mf in field['field_details']['multi_fields']: @@ -179,8 +175,15 @@ def field_assertions_and_warnings(field): # Common +SHORT_LIMIT = 120 + + def single_line_short_description(schema_or_field): - if "\n" in schema_or_field['field_details']['short']: - msg = ("Short descriptions must be single line.\n" + - "Fieldset: '{}'\n{}".format(schema_or_field['field_details']['name'], schema_or_field)) + short_length = len(schema_or_field['field_details']['short']) + if "\n" in schema_or_field['field_details']['short'] or short_length > SHORT_LIMIT: + msg = "Short descriptions must be single line, and under {} characters (current length: {}).\n".format( + SHORT_LIMIT, short_length) + msg += "Offending field or field set: {}\nShort description:\n {}".format( + schema_or_field['field_details']['name'], + schema_or_field['field_details']['short']) raise ValueError(msg) diff --git a/scripts/schema/finalizer.py b/scripts/schema/finalizer.py index 5a8b662810..45abb6a3a9 100644 --- a/scripts/schema/finalizer.py +++ b/scripts/schema/finalizer.py @@ -1,4 +1,5 @@ import copy +import re from schema import visitor @@ -170,7 +171,7 @@ def field_finalizer(details, path): name_array = path + [details['field_details']['node_name']] flat_name = '.'.join(name_array) details['field_details']['flat_name'] = flat_name - details['field_details']['dashed_name'] = flat_name.replace('.', '-').replace('_', '-') + details['field_details']['dashed_name'] = re.sub('[@_\.]', '-', flat_name) if 'multi_fields' in details['field_details']: for mf in details['field_details']['multi_fields']: mf['flat_name'] = flat_name + '.' + mf['name'] diff --git a/scripts/tests/unit/test_schema_cleaner.py b/scripts/tests/unit/test_schema_cleaner.py index 56fa4d5926..ed82218706 100644 --- a/scripts/tests/unit/test_schema_cleaner.py +++ b/scripts/tests/unit/test_schema_cleaner.py @@ -177,9 +177,8 @@ def test_field_simple_cleanup(self): self.assertEqual(my_field['field_details']['name'], 'my_field') self.assertEqual(my_field['field_details']['short'], 'a really short description') self.assertEqual(my_field['field_details']['description'], "a long\n\nmultiline description") - # TODO Temporarily commented out to simplify initial rewrite review - # self.assertEqual(my_field['field_details']['allowed_values'][0]['name'], 'authentication') - # self.assertEqual(my_field['field_details']['allowed_values'][0]['description'], 'when can auth be used?') + self.assertEqual(my_field['field_details']['allowed_values'][0]['name'], 'authentication') + self.assertEqual(my_field['field_details']['allowed_values'][0]['description'], 'when can auth be used?') def test_field_defaults(self): field_min_details = { @@ -249,6 +248,13 @@ def test_multi_field_defaults_and_precalc(self): # common to schemas and fields + def test_very_long_short_description_raises(self): + schema = {'field_details': { + 'name': 'fake_schema', + 'short': "Single line but really long. " * 10}} + with self.assertRaisesRegex(ValueError, 'under 120 characters \(current length: 290\)'): + cleaner.single_line_short_description(schema) + def test_multiline_short_description_raises(self): schema = {'field_details': { 'name': 'fake_schema', diff --git a/scripts/tests/unit/test_schema_finalizer.py b/scripts/tests/unit/test_schema_finalizer.py index 573fc13054..64f3f25458 100644 --- a/scripts/tests/unit/test_schema_finalizer.py +++ b/scripts/tests/unit/test_schema_finalizer.py @@ -234,7 +234,7 @@ def test_calculate_final_values(self): timestamp_details = base_fields['@timestamp']['field_details'] self.assertEqual(timestamp_details['flat_name'], '@timestamp', "Field sets with root=true must not namespace field names with the field set's name") - self.assertEqual(timestamp_details['dashed_name'], '@timestamp') + self.assertEqual(timestamp_details['dashed_name'], '-timestamp') # root=false self.assertEqual(server_fields['ip']['field_details']['flat_name'], 'server.ip', "Field sets with root=false must namespace field names with the field set's name") @@ -251,6 +251,11 @@ def test_calculate_final_values(self): user_full_name_details = user_fields['full_name']['field_details'] self.assertEqual(user_full_name_details['multi_fields'][0]['flat_name'], 'user.full_name.text') + def test_dashed_name_cleanup(self): + details = {'field_details': {'node_name': '@time.stamp_'}} + finalizer.field_finalizer(details, []) + self.assertEqual(details['field_details']['dashed_name'], '-time-stamp-') + # field_group_at_path def test_field_group_at_path_root_destination(self):