diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index 13629f4c09..248375c72e 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -13,6 +13,7 @@ * Generator for the asciidoc rendering of field definitions. #347 * Generator for the Beats fields.ecs.yml file. #379 * Added field formats to all `.bytes` fields and `event.duration`. #385 +* Added `event.code`, `event.sequence` and `event.provider`. #439 ### Improvements diff --git a/code/go/ecs/event.go b/code/go/ecs/event.go index 56fcebe056..f43b4f8f0a 100644 --- a/code/go/ecs/event.go +++ b/code/go/ecs/event.go @@ -37,6 +37,12 @@ type Event struct { // Unique ID to describe the event. ID string `ecs:"id"` + // Identification code for this event, if one exists. + // Some event sources use event codes to identify messages unambiguously, + // regardless of message language or wording adjustments over time. An + // example of this is the Windows Event ID. + Code string `ecs:"code"` + // The kind of the event. // This gives information about what type of information the event // contains, without being specific to the contents of the event. Examples @@ -71,15 +77,26 @@ type Event struct { Type string `ecs:"type"` // Name of the module this data is coming from. - // This information is coming from the modules used in Beats or Logstash. + // If your monitoring agent supports the concept of modules or plugins to + // process events of a given source (e.g. Apache logs), `event.module` + // should contain the name of this module. Module string `ecs:"module"` // Name of the dataset. - // The concept of a `dataset` (fileset / metricset) is used in Beats as a - // subset of modules. It contains the information which is currently stored - // in metricset.name and metricset.module or fileset.name. + // If an event source publishes more than one type of log or events (e.g. + // access log, error log), the dataset is used to specify which one the + // event comes from. + // It's recommended but not required to start the dataset name with the + // module name, followed by a dot, then the dataset name. Dataset string `ecs:"dataset"` + // Source of the event. + // Event transports such as Syslog or the Windows Event Log typically + // mention the source of an event. It can be the name of the software that + // generated the event (e.g. Sysmon, httpd), or of a subsystem of the + // operating system (kernel, Microsoft-Windows-Security-Auditing). + Provider string `ecs:"provider"` + // Severity describes the original severity of the event. What the // different severity values mean can very different between use cases. // It's up to the implementer to make sure severities are consistent across @@ -100,6 +117,12 @@ type Event struct { // difference between the end and start time. Duration time.Duration `ecs:"duration"` + // Sequence number of the event. + // The sequence number is a value published by some event sources, to make + // the exact ordering of events unambiguous, regarless of the timestamp + // precision. + Sequence int64 `ecs:"sequence"` + // This field should be populated when the event's timestamp does not // include timezone information already (e.g. default Syslog timestamps). // It's optional otherwise. diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index 04251bfff9..b8e4c53ea5 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -706,6 +706,19 @@ example: `user-management` // =============================================================== +| event.code +| Identification code for this event, if one exists. + +Some event sources use event codes to identify messages unambiguously, regardless of message language or wording adjustments over time. An example of this is the Windows Event ID. + +type: keyword + +example: `4648` + +| extended + +// =============================================================== + | event.created | event.created contains the date/time when the event was first read by an agent, or by your pipeline. @@ -726,11 +739,13 @@ type: date | event.dataset | Name of the dataset. -The concept of a `dataset` (fileset / metricset) is used in Beats as a subset of modules. It contains the information which is currently stored in metricset.name and metricset.module or fileset.name. +If an event source publishes more than one type of log or events (e.g. access log, error log), the dataset is used to specify which one the event comes from. + +It's recommended but not required to start the dataset name with the module name, followed by a dot, then the dataset name. type: keyword -example: `stats` +example: `apache.access` | core @@ -798,11 +813,11 @@ example: `state` | event.module | Name of the module this data is coming from. -This information is coming from the modules used in Beats or Logstash. +If your monitoring agent supports the concept of modules or plugins to process events of a given source (e.g. Apache logs), `event.module` should contain the name of this module. type: keyword -example: `mysql` +example: `apache` | core @@ -834,6 +849,19 @@ example: `success` // =============================================================== +| event.provider +| Source of the event. + +Event transports such as Syslog or the Windows Event Log typically mention the source of an event. It can be the name of the software that generated the event (e.g. Sysmon, httpd), or of a subsystem of the operating system (kernel, Microsoft-Windows-Security-Auditing). + +type: keyword + +example: `kernel` + +| extended + +// =============================================================== + | event.risk_score | Risk score or priority of the event (e.g. security solutions). Use your system's original value here. @@ -854,6 +882,19 @@ type: float +| extended + +// =============================================================== + +| event.sequence +| Sequence number of the event. + +The sequence number is a value published by some event sources, to make the exact ordering of events unambiguous, regarless of the timestamp precision. + +type: long + + + | extended // =============================================================== diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index 44514e3489..664f02821e 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -583,6 +583,16 @@ multiple actions. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution.' example: user-management + - name: code + level: extended + type: keyword + ignore_above: 1024 + description: 'Identification code for this event, if one exists. + + Some event sources use event codes to identify messages unambiguously, regardless + of message language or wording adjustments over time. An example of this is + the Windows Event ID.' + example: 4648 - name: created level: core type: date @@ -604,10 +614,13 @@ ignore_above: 1024 description: 'Name of the dataset. - The concept of a `dataset` (fileset / metricset) is used in Beats as a subset - of modules. It contains the information which is currently stored in metricset.name - and metricset.module or fileset.name.' - example: stats + If an event source publishes more than one type of log or events (e.g. access + log, error log), the dataset is used to specify which one the event comes + from. + + It''s recommended but not required to start the dataset name with the module + name, followed by a dot, then the dataset name.' + example: apache.access - name: duration level: core type: long @@ -654,8 +667,10 @@ ignore_above: 1024 description: 'Name of the module this data is coming from. - This information is coming from the modules used in Beats or Logstash.' - example: mysql + If your monitoring agent supports the concept of modules or plugins to process + events of a given source (e.g. Apache logs), `event.module` should contain + the name of this module.' + example: apache - name: original level: core type: keyword @@ -677,6 +692,17 @@ versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution.' example: success + - name: provider + level: extended + type: keyword + ignore_above: 1024 + description: 'Source of the event. + + Event transports such as Syslog or the Windows Event Log typically mention + the source of an event. It can be the name of the software that generated + the event (e.g. Sysmon, httpd), or of a subsystem of the operating system + (kernel, Microsoft-Windows-Security-Auditing).' + example: kernel - name: risk_score level: core type: float @@ -690,6 +716,13 @@ This is mainly useful if you use more than one system that assigns risk scores, and you want to see a normalized value across all systems.' + - name: sequence + level: extended + type: long + description: 'Sequence number of the event. + + The sequence number is a value published by some event sources, to make the + exact ordering of events unambiguous, regarless of the timestamp precision.' - name: severity level: core type: long diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv index 938ccd92ac..bc8aee301e 100644 --- a/generated/csv/fields.csv +++ b/generated/csv/fields.csv @@ -71,18 +71,21 @@ error.id,keyword,core,,1.1.0-dev error.message,text,core,,1.1.0-dev event.action,keyword,core,user-password-change,1.1.0-dev event.category,keyword,core,user-management,1.1.0-dev +event.code,keyword,extended,4648,1.1.0-dev event.created,date,core,,1.1.0-dev -event.dataset,keyword,core,stats,1.1.0-dev +event.dataset,keyword,core,apache.access,1.1.0-dev event.duration,long,core,,1.1.0-dev event.end,date,extended,,1.1.0-dev event.hash,keyword,extended,123456789012345678901234567890ABCD,1.1.0-dev event.id,keyword,core,8a4f500d,1.1.0-dev event.kind,keyword,extended,state,1.1.0-dev -event.module,keyword,core,mysql,1.1.0-dev +event.module,keyword,core,apache,1.1.0-dev event.original,keyword,core,Sep 19 08:26:10 host CEF:0|Security| threatmanager|1.0|100| worm successfully stopped|10|src=10.0.0.1 dst=2.1.2.2spt=1232,1.1.0-dev event.outcome,keyword,extended,success,1.1.0-dev +event.provider,keyword,extended,kernel,1.1.0-dev event.risk_score,float,core,,1.1.0-dev event.risk_score_norm,float,extended,,1.1.0-dev +event.sequence,long,extended,,1.1.0-dev event.severity,long,core,7,1.1.0-dev event.start,date,extended,,1.1.0-dev event.timezone,keyword,extended,,1.1.0-dev diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml index 27242d77a9..f40a2d3b71 100644 --- a/generated/ecs/ecs_flat.yml +++ b/generated/ecs/ecs_flat.yml @@ -738,7 +738,7 @@ event.action: ignore_above: 1024 level: core name: action - order: 3 + order: 4 short: The action captured by the event. type: keyword event.category: @@ -753,9 +753,23 @@ event.category: ignore_above: 1024 level: core name: category - order: 2 + order: 3 short: Event category. type: keyword +event.code: + description: 'Identification code for this event, if one exists. + + Some event sources use event codes to identify messages unambiguously, regardless + of message language or wording adjustments over time. An example of this is the + Windows Event ID.' + example: 4648 + flat_name: event.code + ignore_above: 1024 + level: extended + name: code + order: 1 + short: Identification code for this event. + type: keyword event.created: description: 'event.created contains the date/time when the event was first read by an agent, or by your pipeline. @@ -772,21 +786,23 @@ event.created: flat_name: event.created level: core name: created - order: 13 + order: 16 short: Time when the event was first read by an agent or by your pipeline. type: date event.dataset: description: 'Name of the dataset. - The concept of a `dataset` (fileset / metricset) is used in Beats as a subset - of modules. It contains the information which is currently stored in metricset.name - and metricset.module or fileset.name.' - example: stats + If an event source publishes more than one type of log or events (e.g. access + log, error log), the dataset is used to specify which one the event comes from. + + It''s recommended but not required to start the dataset name with the module name, + followed by a dot, then the dataset name.' + example: apache.access flat_name: event.dataset ignore_above: 1024 level: core name: dataset - order: 7 + order: 8 short: Name of the dataset. type: keyword event.duration: @@ -799,7 +815,7 @@ event.duration: input_format: nanoseconds level: core name: duration - order: 11 + order: 13 output_format: asMilliseconds output_precision: 1 short: Duration of the event in nanoseconds. @@ -810,7 +826,7 @@ event.end: flat_name: event.end level: extended name: end - order: 15 + order: 18 short: event.end contains the date when the event ended or when the activity was last observed. type: date @@ -822,7 +838,7 @@ event.hash: ignore_above: 1024 level: extended name: hash - order: 10 + order: 12 short: Hash (perhaps logstash fingerprint) of raw field to be able to demonstrate log integrity. type: keyword @@ -848,19 +864,21 @@ event.kind: ignore_above: 1024 level: extended name: kind - order: 1 + order: 2 short: The kind of the event. type: keyword event.module: description: 'Name of the module this data is coming from. - This information is coming from the modules used in Beats or Logstash.' - example: mysql + If your monitoring agent supports the concept of modules or plugins to process + events of a given source (e.g. Apache logs), `event.module` should contain the + name of this module.' + example: apache flat_name: event.module ignore_above: 1024 level: core name: module - order: 6 + order: 7 short: Name of the module this data is coming from. type: keyword event.original: @@ -876,7 +894,7 @@ event.original: index: false level: core name: original - order: 9 + order: 11 short: Raw text message of entire event. type: keyword event.outcome: @@ -891,16 +909,30 @@ event.outcome: ignore_above: 1024 level: extended name: outcome - order: 4 + order: 5 short: The outcome of the event. type: keyword +event.provider: + description: 'Source of the event. + + Event transports such as Syslog or the Windows Event Log typically mention the + source of an event. It can be the name of the software that generated the event + (e.g. Sysmon, httpd), or of a subsystem of the operating system (kernel, Microsoft-Windows-Security-Auditing).' + example: kernel + flat_name: event.provider + ignore_above: 1024 + level: extended + name: provider + order: 9 + short: Source of the event. + type: keyword event.risk_score: description: Risk score or priority of the event (e.g. security solutions). Use your system's original value here. flat_name: event.risk_score level: core name: risk_score - order: 16 + order: 19 short: Risk score or priority of the event (e.g. security solutions). Use your system's original value here. type: float @@ -913,9 +945,20 @@ event.risk_score_norm: flat_name: event.risk_score_norm level: extended name: risk_score_norm - order: 17 + order: 20 short: Normalized risk score or priority of the event (0-100). type: float +event.sequence: + description: 'Sequence number of the event. + + The sequence number is a value published by some event sources, to make the exact + ordering of events unambiguous, regarless of the timestamp precision.' + flat_name: event.sequence + level: extended + name: sequence + order: 14 + short: Sequence number of the event. + type: long event.severity: description: Severity describes the original severity of the event. What the different severity values mean can very different between use cases. It's up to the implementer @@ -924,7 +967,7 @@ event.severity: flat_name: event.severity level: core name: severity - order: 8 + order: 10 short: Original severity of the event. type: long event.start: @@ -933,7 +976,7 @@ event.start: flat_name: event.start level: extended name: start - order: 14 + order: 17 short: event.start contains the date when the event started or when the activity was first observed. type: date @@ -948,7 +991,7 @@ event.timezone: ignore_above: 1024 level: extended name: timezone - order: 12 + order: 15 short: Event time zone. type: keyword event.type: @@ -959,7 +1002,7 @@ event.type: ignore_above: 1024 level: core name: type - order: 5 + order: 6 short: Reserved for future usage. type: keyword file.ctime: diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index 0f9c623dee..2bf38813de 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -912,7 +912,7 @@ event: ignore_above: 1024 level: core name: action - order: 3 + order: 4 short: The action captured by the event. type: keyword category: @@ -927,9 +927,23 @@ event: ignore_above: 1024 level: core name: category - order: 2 + order: 3 short: Event category. type: keyword + code: + description: 'Identification code for this event, if one exists. + + Some event sources use event codes to identify messages unambiguously, regardless + of message language or wording adjustments over time. An example of this is + the Windows Event ID.' + example: 4648 + flat_name: event.code + ignore_above: 1024 + level: extended + name: code + order: 1 + short: Identification code for this event. + type: keyword created: description: 'event.created contains the date/time when the event was first read by an agent, or by your pipeline. @@ -946,21 +960,24 @@ event: flat_name: event.created level: core name: created - order: 13 + order: 16 short: Time when the event was first read by an agent or by your pipeline. type: date dataset: description: 'Name of the dataset. - The concept of a `dataset` (fileset / metricset) is used in Beats as a subset - of modules. It contains the information which is currently stored in metricset.name - and metricset.module or fileset.name.' - example: stats + If an event source publishes more than one type of log or events (e.g. access + log, error log), the dataset is used to specify which one the event comes + from. + + It''s recommended but not required to start the dataset name with the module + name, followed by a dot, then the dataset name.' + example: apache.access flat_name: event.dataset ignore_above: 1024 level: core name: dataset - order: 7 + order: 8 short: Name of the dataset. type: keyword duration: @@ -973,7 +990,7 @@ event: input_format: nanoseconds level: core name: duration - order: 11 + order: 13 output_format: asMilliseconds output_precision: 1 short: Duration of the event in nanoseconds. @@ -984,7 +1001,7 @@ event: flat_name: event.end level: extended name: end - order: 15 + order: 18 short: event.end contains the date when the event ended or when the activity was last observed. type: date @@ -996,7 +1013,7 @@ event: ignore_above: 1024 level: extended name: hash - order: 10 + order: 12 short: Hash (perhaps logstash fingerprint) of raw field to be able to demonstrate log integrity. type: keyword @@ -1022,19 +1039,21 @@ event: ignore_above: 1024 level: extended name: kind - order: 1 + order: 2 short: The kind of the event. type: keyword module: description: 'Name of the module this data is coming from. - This information is coming from the modules used in Beats or Logstash.' - example: mysql + If your monitoring agent supports the concept of modules or plugins to process + events of a given source (e.g. Apache logs), `event.module` should contain + the name of this module.' + example: apache flat_name: event.module ignore_above: 1024 level: core name: module - order: 6 + order: 7 short: Name of the module this data is coming from. type: keyword original: @@ -1050,7 +1069,7 @@ event: index: false level: core name: original - order: 9 + order: 11 short: Raw text message of entire event. type: keyword outcome: @@ -1065,16 +1084,31 @@ event: ignore_above: 1024 level: extended name: outcome - order: 4 + order: 5 short: The outcome of the event. type: keyword + provider: + description: 'Source of the event. + + Event transports such as Syslog or the Windows Event Log typically mention + the source of an event. It can be the name of the software that generated + the event (e.g. Sysmon, httpd), or of a subsystem of the operating system + (kernel, Microsoft-Windows-Security-Auditing).' + example: kernel + flat_name: event.provider + ignore_above: 1024 + level: extended + name: provider + order: 9 + short: Source of the event. + type: keyword risk_score: description: Risk score or priority of the event (e.g. security solutions). Use your system's original value here. flat_name: event.risk_score level: core name: risk_score - order: 16 + order: 19 short: Risk score or priority of the event (e.g. security solutions). Use your system's original value here. type: float @@ -1087,9 +1121,20 @@ event: flat_name: event.risk_score_norm level: extended name: risk_score_norm - order: 17 + order: 20 short: Normalized risk score or priority of the event (0-100). type: float + sequence: + description: 'Sequence number of the event. + + The sequence number is a value published by some event sources, to make the + exact ordering of events unambiguous, regarless of the timestamp precision.' + flat_name: event.sequence + level: extended + name: sequence + order: 14 + short: Sequence number of the event. + type: long severity: description: Severity describes the original severity of the event. What the different severity values mean can very different between use cases. It's @@ -1098,7 +1143,7 @@ event: flat_name: event.severity level: core name: severity - order: 8 + order: 10 short: Original severity of the event. type: long start: @@ -1107,7 +1152,7 @@ event: flat_name: event.start level: extended name: start - order: 14 + order: 17 short: event.start contains the date when the event started or when the activity was first observed. type: date @@ -1122,7 +1167,7 @@ event: ignore_above: 1024 level: extended name: timezone - order: 12 + order: 15 short: Event time zone. type: keyword type: @@ -1133,7 +1178,7 @@ event: ignore_above: 1024 level: core name: type - order: 5 + order: 6 short: Reserved for future usage. type: keyword group: 2 diff --git a/generated/elasticsearch/6/template.json b/generated/elasticsearch/6/template.json index 8fbc51a27a..aaada03099 100644 --- a/generated/elasticsearch/6/template.json +++ b/generated/elasticsearch/6/template.json @@ -354,6 +354,10 @@ "ignore_above": 1024, "type": "keyword" }, + "code": { + "ignore_above": 1024, + "type": "keyword" + }, "created": { "type": "date" }, @@ -393,12 +397,19 @@ "ignore_above": 1024, "type": "keyword" }, + "provider": { + "ignore_above": 1024, + "type": "keyword" + }, "risk_score": { "type": "float" }, "risk_score_norm": { "type": "float" }, + "sequence": { + "type": "long" + }, "severity": { "type": "long" }, diff --git a/generated/elasticsearch/7/template.json b/generated/elasticsearch/7/template.json index bd4b921677..be767a93a9 100644 --- a/generated/elasticsearch/7/template.json +++ b/generated/elasticsearch/7/template.json @@ -353,6 +353,10 @@ "ignore_above": 1024, "type": "keyword" }, + "code": { + "ignore_above": 1024, + "type": "keyword" + }, "created": { "type": "date" }, @@ -392,12 +396,19 @@ "ignore_above": 1024, "type": "keyword" }, + "provider": { + "ignore_above": 1024, + "type": "keyword" + }, "risk_score": { "type": "float" }, "risk_score_norm": { "type": "float" }, + "sequence": { + "type": "long" + }, "severity": { "type": "long" }, diff --git a/generated/legacy/template.json b/generated/legacy/template.json index 82783af8fa..37e031cefe 100644 --- a/generated/legacy/template.json +++ b/generated/legacy/template.json @@ -212,6 +212,10 @@ "ignore_above": 1024, "type": "keyword" }, + "code": { + "ignore_above": 1024, + "type": "keyword" + }, "created": { "type": "date" }, @@ -251,12 +255,19 @@ "ignore_above": 1024, "type": "keyword" }, + "provider": { + "ignore_above": 1024, + "type": "keyword" + }, "risk_score": { "type": "float" }, "risk_score_norm": { "type": "float" }, + "sequence": { + "type": "long" + }, "severity": { "type": "long" }, diff --git a/schemas/event.yml b/schemas/event.yml index 4918a98bc5..2e904fa96a 100644 --- a/schemas/event.yml +++ b/schemas/event.yml @@ -25,6 +25,18 @@ Unique ID to describe the event. example: 8a4f500d + - name: code + level: extended + type: keyword + short: Identification code for this event. + description: > + Identification code for this event, if one exists. + + Some event sources use event codes to identify messages unambiguously, + regardless of message language or wording adjustments over time. + An example of this is the Windows Event ID. + example: 4648 + - name: kind level: extended type: keyword @@ -96,8 +108,10 @@ description: > Name of the module this data is coming from. - This information is coming from the modules used in Beats or Logstash. - example: mysql + If your monitoring agent supports the concept of modules or plugins to + process events of a given source (e.g. Apache logs), + `event.module` should contain the name of this module. + example: apache - name: dataset level: core @@ -106,10 +120,27 @@ description: > Name of the dataset. - The concept of a `dataset` (fileset / metricset) is used in Beats as a - subset of modules. It contains the information which is currently - stored in metricset.name and metricset.module or fileset.name. - example: stats + If an event source publishes more than one type of log or events + (e.g. access log, error log), the dataset is used to specify which + one the event comes from. + + It's recommended but not required to start the dataset name with + the module name, followed by a dot, then the dataset name. + example: apache.access + + - name: provider + level: extended + type: keyword + short: Source of the event. + description: > + Source of the event. + + Event transports such as Syslog or the Windows Event Log typically + mention the source of an event. It can be the name of the + software that generated the event (e.g. Sysmon, httpd), + or of a subsystem of the operating system (kernel, Microsoft-Windows-Security-Auditing). + + example: kernel - name: severity level: core @@ -163,6 +194,16 @@ If event.start and event.end are known this value should be the difference between the end and start time. + - name: sequence + level: extended + type: long + short: Sequence number of the event. + description: > + Sequence number of the event. + + The sequence number is a value published by some event sources, to make the + exact ordering of events unambiguous, regarless of the timestamp precision. + - name: timezone level: extended type: keyword diff --git a/use-cases/auditbeat.md b/use-cases/auditbeat.md index 515c6245de..1ab9c2f7bf 100644 --- a/use-cases/auditbeat.md +++ b/use-cases/auditbeat.md @@ -7,7 +7,7 @@ ECS usage in Auditbeat. | Field | Description | Level | Type | Example | |---|---|---|---|---| -| [event.module](../README.md#event.module) | Auditbeat module name. | core | keyword | `mysql` | +| [event.module](../README.md#event.module) | Auditbeat module name. | core | keyword | `apache` | | *file.** | *File attributes.
* | | | | | [file.path](../README.md#file.path) | The path to the file. | extended | keyword | | | [file.target_path](../README.md#file.target_path) | The target path for symlinks. | extended | keyword | |