From 746c156da866a6fc043b0eac92c3d6a52b3e6da6 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 30 Oct 2020 11:10:13 -0400 Subject: [PATCH 01/17] Apply new user field reuse in main ECS field definitions. --- docs/field-details.asciidoc | 20 +- experimental/schemas/user.yml | 8 - generated/beats/fields.ecs.yml | 237 ++++++++++++++ generated/csv/fields.csv | 36 ++ generated/ecs/ecs_flat.yml | 396 ++++++++++++++++++++++ generated/ecs/ecs_nested.yml | 417 ++++++++++++++++++++++++ generated/elasticsearch/6/template.json | 180 ++++++++++ generated/elasticsearch/7/template.json | 180 ++++++++++ schemas/user.yml | 6 + 9 files changed, 1471 insertions(+), 9 deletions(-) diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index ddcb587a24..56f63004b0 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -6565,7 +6565,7 @@ example: `["kibana_admin", "reporting_user"]` [discrete] ==== Field Reuse -The `user` fields are expected to be nested at: `client.user`, `destination.user`, `host.user`, `server.user`, `source.user`. +The `user` fields are expected to be nested at: `client.user`, `destination.user`, `host.user`, `server.user`, `source.user`, `user.changes`, `user.effective`, `user.target`. Note also that the `user` fields may be used directly at the root of the events. @@ -6583,12 +6583,30 @@ Note also that the `user` fields may be used directly at the root of the events. // =============================================================== +| <> +| Fields to describe the user relevant to the event. + +// =============================================================== + + +| <> +| Fields to describe the user relevant to the event. + +// =============================================================== + + | <> | User's group relevant to the event. // =============================================================== +| <> +| Fields to describe the user relevant to the event. + +// =============================================================== + + |===== [[ecs-user_agent]] diff --git a/experimental/schemas/user.yml b/experimental/schemas/user.yml index b2af27d5ab..89e182fbee 100644 --- a/experimental/schemas/user.yml +++ b/experimental/schemas/user.yml @@ -7,11 +7,3 @@ type: wildcard - name: email type: wildcard - reusable: - expected: - - at: user - as: target - - at: user - as: effective - - at: user - as: changes diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml index b2d3e4ef5a..d589e62e19 100644 --- a/generated/beats/fields.ecs.yml +++ b/generated/beats/fields.ecs.yml @@ -5443,6 +5443,85 @@ provide an array that includes all of them.' type: group fields: + - name: changes.domain + level: extended + type: keyword + ignore_above: 1024 + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + default_field: false + - name: changes.email + level: extended + type: keyword + ignore_above: 1024 + description: User email address. + default_field: false + - name: changes.full_name + level: extended + type: keyword + ignore_above: 1024 + multi_fields: + - name: text + type: text + norms: false + description: User's full name, if available. + example: Albert Einstein + default_field: false + - name: changes.group.domain + level: extended + type: keyword + ignore_above: 1024 + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + default_field: false + - name: changes.group.id + level: extended + type: keyword + ignore_above: 1024 + description: Unique identifier for the group on the system/platform. + default_field: false + - name: changes.group.name + level: extended + type: keyword + ignore_above: 1024 + description: Name of the group. + default_field: false + - name: changes.hash + level: extended + type: keyword + ignore_above: 1024 + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + default_field: false + - name: changes.id + level: core + type: keyword + ignore_above: 1024 + description: Unique identifier of the user. + default_field: false + - name: changes.name + level: core + type: keyword + ignore_above: 1024 + multi_fields: + - name: text + type: text + norms: false + description: Short name or login of the user. + example: albert + default_field: false + - name: changes.roles + level: extended + type: keyword + ignore_above: 1024 + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + default_field: false - name: domain level: extended type: keyword @@ -5450,6 +5529,85 @@ description: 'Name of the directory the user is a member of. For example, an LDAP or Active Directory domain name.' + - name: effective.domain + level: extended + type: keyword + ignore_above: 1024 + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + default_field: false + - name: effective.email + level: extended + type: keyword + ignore_above: 1024 + description: User email address. + default_field: false + - name: effective.full_name + level: extended + type: keyword + ignore_above: 1024 + multi_fields: + - name: text + type: text + norms: false + description: User's full name, if available. + example: Albert Einstein + default_field: false + - name: effective.group.domain + level: extended + type: keyword + ignore_above: 1024 + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + default_field: false + - name: effective.group.id + level: extended + type: keyword + ignore_above: 1024 + description: Unique identifier for the group on the system/platform. + default_field: false + - name: effective.group.name + level: extended + type: keyword + ignore_above: 1024 + description: Name of the group. + default_field: false + - name: effective.hash + level: extended + type: keyword + ignore_above: 1024 + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + default_field: false + - name: effective.id + level: core + type: keyword + ignore_above: 1024 + description: Unique identifier of the user. + default_field: false + - name: effective.name + level: core + type: keyword + ignore_above: 1024 + multi_fields: + - name: text + type: text + norms: false + description: Short name or login of the user. + example: albert + default_field: false + - name: effective.roles + level: extended + type: keyword + ignore_above: 1024 + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + default_field: false - name: email level: extended type: keyword @@ -5515,6 +5673,85 @@ description: Array of user roles at the time of the event. example: '["kibana_admin", "reporting_user"]' default_field: false + - name: target.domain + level: extended + type: keyword + ignore_above: 1024 + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + default_field: false + - name: target.email + level: extended + type: keyword + ignore_above: 1024 + description: User email address. + default_field: false + - name: target.full_name + level: extended + type: keyword + ignore_above: 1024 + multi_fields: + - name: text + type: text + norms: false + description: User's full name, if available. + example: Albert Einstein + default_field: false + - name: target.group.domain + level: extended + type: keyword + ignore_above: 1024 + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + default_field: false + - name: target.group.id + level: extended + type: keyword + ignore_above: 1024 + description: Unique identifier for the group on the system/platform. + default_field: false + - name: target.group.name + level: extended + type: keyword + ignore_above: 1024 + description: Name of the group. + default_field: false + - name: target.hash + level: extended + type: keyword + ignore_above: 1024 + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + default_field: false + - name: target.id + level: core + type: keyword + ignore_above: 1024 + description: Unique identifier of the user. + default_field: false + - name: target.name + level: core + type: keyword + ignore_above: 1024 + multi_fields: + - name: text + type: text + norms: false + description: Short name or login of the user. + example: albert + default_field: false + - name: target.roles + level: extended + type: keyword + ignore_above: 1024 + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + default_field: false - name: user_agent title: User agent group: 2 diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv index 2a8688c22b..abc0682289 100644 --- a/generated/csv/fields.csv +++ b/generated/csv/fields.csv @@ -644,7 +644,31 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 2.0.0-dev,true,url,url.subdomain,keyword,extended,,east,The subdomain of the domain. 2.0.0-dev,true,url,url.top_level_domain,keyword,extended,,co.uk,"The effective top level domain (com, org, net, co.uk)." 2.0.0-dev,true,url,url.username,keyword,extended,,,Username of the request. +2.0.0-dev,true,user,user.changes.domain,keyword,extended,,,Name of the directory the user is a member of. +2.0.0-dev,true,user,user.changes.email,keyword,extended,,,User email address. +2.0.0-dev,true,user,user.changes.full_name,keyword,extended,,Albert Einstein,"User's full name, if available." +2.0.0-dev,true,user,user.changes.full_name.text,text,extended,,Albert Einstein,"User's full name, if available." +2.0.0-dev,true,user,user.changes.group.domain,keyword,extended,,,Name of the directory the group is a member of. +2.0.0-dev,true,user,user.changes.group.id,keyword,extended,,,Unique identifier for the group on the system/platform. +2.0.0-dev,true,user,user.changes.group.name,keyword,extended,,,Name of the group. +2.0.0-dev,true,user,user.changes.hash,keyword,extended,,,Unique user hash to correlate information for a user in anonymized form. +2.0.0-dev,true,user,user.changes.id,keyword,core,,,Unique identifier of the user. +2.0.0-dev,true,user,user.changes.name,keyword,core,,albert,Short name or login of the user. +2.0.0-dev,true,user,user.changes.name.text,text,core,,albert,Short name or login of the user. +2.0.0-dev,true,user,user.changes.roles,keyword,extended,array,"[""kibana_admin"", ""reporting_user""]",Array of user roles at the time of the event. 2.0.0-dev,true,user,user.domain,keyword,extended,,,Name of the directory the user is a member of. +2.0.0-dev,true,user,user.effective.domain,keyword,extended,,,Name of the directory the user is a member of. +2.0.0-dev,true,user,user.effective.email,keyword,extended,,,User email address. +2.0.0-dev,true,user,user.effective.full_name,keyword,extended,,Albert Einstein,"User's full name, if available." +2.0.0-dev,true,user,user.effective.full_name.text,text,extended,,Albert Einstein,"User's full name, if available." +2.0.0-dev,true,user,user.effective.group.domain,keyword,extended,,,Name of the directory the group is a member of. +2.0.0-dev,true,user,user.effective.group.id,keyword,extended,,,Unique identifier for the group on the system/platform. +2.0.0-dev,true,user,user.effective.group.name,keyword,extended,,,Name of the group. +2.0.0-dev,true,user,user.effective.hash,keyword,extended,,,Unique user hash to correlate information for a user in anonymized form. +2.0.0-dev,true,user,user.effective.id,keyword,core,,,Unique identifier of the user. +2.0.0-dev,true,user,user.effective.name,keyword,core,,albert,Short name or login of the user. +2.0.0-dev,true,user,user.effective.name.text,text,core,,albert,Short name or login of the user. +2.0.0-dev,true,user,user.effective.roles,keyword,extended,array,"[""kibana_admin"", ""reporting_user""]",Array of user roles at the time of the event. 2.0.0-dev,true,user,user.email,keyword,extended,,,User email address. 2.0.0-dev,true,user,user.full_name,keyword,extended,,Albert Einstein,"User's full name, if available." 2.0.0-dev,true,user,user.full_name.text,text,extended,,Albert Einstein,"User's full name, if available." @@ -656,6 +680,18 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description 2.0.0-dev,true,user,user.name,keyword,core,,albert,Short name or login of the user. 2.0.0-dev,true,user,user.name.text,text,core,,albert,Short name or login of the user. 2.0.0-dev,true,user,user.roles,keyword,extended,array,"[""kibana_admin"", ""reporting_user""]",Array of user roles at the time of the event. +2.0.0-dev,true,user,user.target.domain,keyword,extended,,,Name of the directory the user is a member of. +2.0.0-dev,true,user,user.target.email,keyword,extended,,,User email address. +2.0.0-dev,true,user,user.target.full_name,keyword,extended,,Albert Einstein,"User's full name, if available." +2.0.0-dev,true,user,user.target.full_name.text,text,extended,,Albert Einstein,"User's full name, if available." +2.0.0-dev,true,user,user.target.group.domain,keyword,extended,,,Name of the directory the group is a member of. +2.0.0-dev,true,user,user.target.group.id,keyword,extended,,,Unique identifier for the group on the system/platform. +2.0.0-dev,true,user,user.target.group.name,keyword,extended,,,Name of the group. +2.0.0-dev,true,user,user.target.hash,keyword,extended,,,Unique user hash to correlate information for a user in anonymized form. +2.0.0-dev,true,user,user.target.id,keyword,core,,,Unique identifier of the user. +2.0.0-dev,true,user,user.target.name,keyword,core,,albert,Short name or login of the user. +2.0.0-dev,true,user,user.target.name.text,text,core,,albert,Short name or login of the user. +2.0.0-dev,true,user,user.target.roles,keyword,extended,array,"[""kibana_admin"", ""reporting_user""]",Array of user roles at the time of the event. 2.0.0-dev,true,user_agent,user_agent.device.name,keyword,extended,,iPhone,Name of the device. 2.0.0-dev,true,user_agent,user_agent.name,keyword,extended,,Safari,Name of the user agent. 2.0.0-dev,true,user_agent,user_agent.original,keyword,extended,,"Mozilla/5.0 (iPhone; CPU iPhone OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1",Unparsed user_agent string. diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml index 9447fa982b..0e0193822c 100644 --- a/generated/ecs/ecs_flat.yml +++ b/generated/ecs/ecs_flat.yml @@ -8269,6 +8269,138 @@ url.username: normalize: [] short: Username of the request. type: keyword +user.changes.domain: + dashed_name: user-changes-domain + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.changes.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: user + short: Name of the directory the user is a member of. + type: keyword +user.changes.email: + dashed_name: user-changes-email + description: User email address. + flat_name: user.changes.email + ignore_above: 1024 + level: extended + name: email + normalize: [] + original_fieldset: user + short: User email address. + type: keyword +user.changes.full_name: + dashed_name: user-changes-full-name + description: User's full name, if available. + example: Albert Einstein + flat_name: user.changes.full_name + ignore_above: 1024 + level: extended + multi_fields: + - flat_name: user.changes.full_name.text + name: text + norms: false + type: text + name: full_name + normalize: [] + original_fieldset: user + short: User's full name, if available. + type: keyword +user.changes.group.domain: + dashed_name: user-changes-group-domain + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.changes.group.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: group + short: Name of the directory the group is a member of. + type: keyword +user.changes.group.id: + dashed_name: user-changes-group-id + description: Unique identifier for the group on the system/platform. + flat_name: user.changes.group.id + ignore_above: 1024 + level: extended + name: id + normalize: [] + original_fieldset: group + short: Unique identifier for the group on the system/platform. + type: keyword +user.changes.group.name: + dashed_name: user-changes-group-name + description: Name of the group. + flat_name: user.changes.group.name + ignore_above: 1024 + level: extended + name: name + normalize: [] + original_fieldset: group + short: Name of the group. + type: keyword +user.changes.hash: + dashed_name: user-changes-hash + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + flat_name: user.changes.hash + ignore_above: 1024 + level: extended + name: hash + normalize: [] + original_fieldset: user + short: Unique user hash to correlate information for a user in anonymized form. + type: keyword +user.changes.id: + dashed_name: user-changes-id + description: Unique identifier of the user. + flat_name: user.changes.id + ignore_above: 1024 + level: core + name: id + normalize: [] + original_fieldset: user + short: Unique identifier of the user. + type: keyword +user.changes.name: + dashed_name: user-changes-name + description: Short name or login of the user. + example: albert + flat_name: user.changes.name + ignore_above: 1024 + level: core + multi_fields: + - flat_name: user.changes.name.text + name: text + norms: false + type: text + name: name + normalize: [] + original_fieldset: user + short: Short name or login of the user. + type: keyword +user.changes.roles: + dashed_name: user-changes-roles + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + flat_name: user.changes.roles + ignore_above: 1024 + level: extended + name: roles + normalize: + - array + original_fieldset: user + short: Array of user roles at the time of the event. + type: keyword user.domain: dashed_name: user-domain description: 'Name of the directory the user is a member of. @@ -8281,6 +8413,138 @@ user.domain: normalize: [] short: Name of the directory the user is a member of. type: keyword +user.effective.domain: + dashed_name: user-effective-domain + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.effective.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: user + short: Name of the directory the user is a member of. + type: keyword +user.effective.email: + dashed_name: user-effective-email + description: User email address. + flat_name: user.effective.email + ignore_above: 1024 + level: extended + name: email + normalize: [] + original_fieldset: user + short: User email address. + type: keyword +user.effective.full_name: + dashed_name: user-effective-full-name + description: User's full name, if available. + example: Albert Einstein + flat_name: user.effective.full_name + ignore_above: 1024 + level: extended + multi_fields: + - flat_name: user.effective.full_name.text + name: text + norms: false + type: text + name: full_name + normalize: [] + original_fieldset: user + short: User's full name, if available. + type: keyword +user.effective.group.domain: + dashed_name: user-effective-group-domain + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.effective.group.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: group + short: Name of the directory the group is a member of. + type: keyword +user.effective.group.id: + dashed_name: user-effective-group-id + description: Unique identifier for the group on the system/platform. + flat_name: user.effective.group.id + ignore_above: 1024 + level: extended + name: id + normalize: [] + original_fieldset: group + short: Unique identifier for the group on the system/platform. + type: keyword +user.effective.group.name: + dashed_name: user-effective-group-name + description: Name of the group. + flat_name: user.effective.group.name + ignore_above: 1024 + level: extended + name: name + normalize: [] + original_fieldset: group + short: Name of the group. + type: keyword +user.effective.hash: + dashed_name: user-effective-hash + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + flat_name: user.effective.hash + ignore_above: 1024 + level: extended + name: hash + normalize: [] + original_fieldset: user + short: Unique user hash to correlate information for a user in anonymized form. + type: keyword +user.effective.id: + dashed_name: user-effective-id + description: Unique identifier of the user. + flat_name: user.effective.id + ignore_above: 1024 + level: core + name: id + normalize: [] + original_fieldset: user + short: Unique identifier of the user. + type: keyword +user.effective.name: + dashed_name: user-effective-name + description: Short name or login of the user. + example: albert + flat_name: user.effective.name + ignore_above: 1024 + level: core + multi_fields: + - flat_name: user.effective.name.text + name: text + norms: false + type: text + name: name + normalize: [] + original_fieldset: user + short: Short name or login of the user. + type: keyword +user.effective.roles: + dashed_name: user-effective-roles + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + flat_name: user.effective.roles + ignore_above: 1024 + level: extended + name: roles + normalize: + - array + original_fieldset: user + short: Array of user roles at the time of the event. + type: keyword user.email: dashed_name: user-email description: User email address. @@ -8394,6 +8658,138 @@ user.roles: - array short: Array of user roles at the time of the event. type: keyword +user.target.domain: + dashed_name: user-target-domain + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.target.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: user + short: Name of the directory the user is a member of. + type: keyword +user.target.email: + dashed_name: user-target-email + description: User email address. + flat_name: user.target.email + ignore_above: 1024 + level: extended + name: email + normalize: [] + original_fieldset: user + short: User email address. + type: keyword +user.target.full_name: + dashed_name: user-target-full-name + description: User's full name, if available. + example: Albert Einstein + flat_name: user.target.full_name + ignore_above: 1024 + level: extended + multi_fields: + - flat_name: user.target.full_name.text + name: text + norms: false + type: text + name: full_name + normalize: [] + original_fieldset: user + short: User's full name, if available. + type: keyword +user.target.group.domain: + dashed_name: user-target-group-domain + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.target.group.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: group + short: Name of the directory the group is a member of. + type: keyword +user.target.group.id: + dashed_name: user-target-group-id + description: Unique identifier for the group on the system/platform. + flat_name: user.target.group.id + ignore_above: 1024 + level: extended + name: id + normalize: [] + original_fieldset: group + short: Unique identifier for the group on the system/platform. + type: keyword +user.target.group.name: + dashed_name: user-target-group-name + description: Name of the group. + flat_name: user.target.group.name + ignore_above: 1024 + level: extended + name: name + normalize: [] + original_fieldset: group + short: Name of the group. + type: keyword +user.target.hash: + dashed_name: user-target-hash + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + flat_name: user.target.hash + ignore_above: 1024 + level: extended + name: hash + normalize: [] + original_fieldset: user + short: Unique user hash to correlate information for a user in anonymized form. + type: keyword +user.target.id: + dashed_name: user-target-id + description: Unique identifier of the user. + flat_name: user.target.id + ignore_above: 1024 + level: core + name: id + normalize: [] + original_fieldset: user + short: Unique identifier of the user. + type: keyword +user.target.name: + dashed_name: user-target-name + description: Short name or login of the user. + example: albert + flat_name: user.target.name + ignore_above: 1024 + level: core + multi_fields: + - flat_name: user.target.name.text + name: text + norms: false + type: text + name: name + normalize: [] + original_fieldset: user + short: Short name or login of the user. + type: keyword +user.target.roles: + dashed_name: user-target-roles + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + flat_name: user.target.roles + ignore_above: 1024 + level: extended + name: roles + normalize: + - array + original_fieldset: user + short: Array of user roles at the time of the event. + type: keyword user_agent.device.name: dashed_name: user-agent-device-name description: Name of the device. diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index ca9424eaed..ab5104be05 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -9532,6 +9532,138 @@ user: Fields can have one entry or multiple entries. If a user has more than one id, provide an array that includes all of them.' fields: + user.changes.domain: + dashed_name: user-changes-domain + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.changes.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: user + short: Name of the directory the user is a member of. + type: keyword + user.changes.email: + dashed_name: user-changes-email + description: User email address. + flat_name: user.changes.email + ignore_above: 1024 + level: extended + name: email + normalize: [] + original_fieldset: user + short: User email address. + type: keyword + user.changes.full_name: + dashed_name: user-changes-full-name + description: User's full name, if available. + example: Albert Einstein + flat_name: user.changes.full_name + ignore_above: 1024 + level: extended + multi_fields: + - flat_name: user.changes.full_name.text + name: text + norms: false + type: text + name: full_name + normalize: [] + original_fieldset: user + short: User's full name, if available. + type: keyword + user.changes.group.domain: + dashed_name: user-changes-group-domain + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.changes.group.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: group + short: Name of the directory the group is a member of. + type: keyword + user.changes.group.id: + dashed_name: user-changes-group-id + description: Unique identifier for the group on the system/platform. + flat_name: user.changes.group.id + ignore_above: 1024 + level: extended + name: id + normalize: [] + original_fieldset: group + short: Unique identifier for the group on the system/platform. + type: keyword + user.changes.group.name: + dashed_name: user-changes-group-name + description: Name of the group. + flat_name: user.changes.group.name + ignore_above: 1024 + level: extended + name: name + normalize: [] + original_fieldset: group + short: Name of the group. + type: keyword + user.changes.hash: + dashed_name: user-changes-hash + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + flat_name: user.changes.hash + ignore_above: 1024 + level: extended + name: hash + normalize: [] + original_fieldset: user + short: Unique user hash to correlate information for a user in anonymized form. + type: keyword + user.changes.id: + dashed_name: user-changes-id + description: Unique identifier of the user. + flat_name: user.changes.id + ignore_above: 1024 + level: core + name: id + normalize: [] + original_fieldset: user + short: Unique identifier of the user. + type: keyword + user.changes.name: + dashed_name: user-changes-name + description: Short name or login of the user. + example: albert + flat_name: user.changes.name + ignore_above: 1024 + level: core + multi_fields: + - flat_name: user.changes.name.text + name: text + norms: false + type: text + name: name + normalize: [] + original_fieldset: user + short: Short name or login of the user. + type: keyword + user.changes.roles: + dashed_name: user-changes-roles + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + flat_name: user.changes.roles + ignore_above: 1024 + level: extended + name: roles + normalize: + - array + original_fieldset: user + short: Array of user roles at the time of the event. + type: keyword user.domain: dashed_name: user-domain description: 'Name of the directory the user is a member of. @@ -9544,6 +9676,138 @@ user: normalize: [] short: Name of the directory the user is a member of. type: keyword + user.effective.domain: + dashed_name: user-effective-domain + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.effective.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: user + short: Name of the directory the user is a member of. + type: keyword + user.effective.email: + dashed_name: user-effective-email + description: User email address. + flat_name: user.effective.email + ignore_above: 1024 + level: extended + name: email + normalize: [] + original_fieldset: user + short: User email address. + type: keyword + user.effective.full_name: + dashed_name: user-effective-full-name + description: User's full name, if available. + example: Albert Einstein + flat_name: user.effective.full_name + ignore_above: 1024 + level: extended + multi_fields: + - flat_name: user.effective.full_name.text + name: text + norms: false + type: text + name: full_name + normalize: [] + original_fieldset: user + short: User's full name, if available. + type: keyword + user.effective.group.domain: + dashed_name: user-effective-group-domain + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.effective.group.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: group + short: Name of the directory the group is a member of. + type: keyword + user.effective.group.id: + dashed_name: user-effective-group-id + description: Unique identifier for the group on the system/platform. + flat_name: user.effective.group.id + ignore_above: 1024 + level: extended + name: id + normalize: [] + original_fieldset: group + short: Unique identifier for the group on the system/platform. + type: keyword + user.effective.group.name: + dashed_name: user-effective-group-name + description: Name of the group. + flat_name: user.effective.group.name + ignore_above: 1024 + level: extended + name: name + normalize: [] + original_fieldset: group + short: Name of the group. + type: keyword + user.effective.hash: + dashed_name: user-effective-hash + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + flat_name: user.effective.hash + ignore_above: 1024 + level: extended + name: hash + normalize: [] + original_fieldset: user + short: Unique user hash to correlate information for a user in anonymized form. + type: keyword + user.effective.id: + dashed_name: user-effective-id + description: Unique identifier of the user. + flat_name: user.effective.id + ignore_above: 1024 + level: core + name: id + normalize: [] + original_fieldset: user + short: Unique identifier of the user. + type: keyword + user.effective.name: + dashed_name: user-effective-name + description: Short name or login of the user. + example: albert + flat_name: user.effective.name + ignore_above: 1024 + level: core + multi_fields: + - flat_name: user.effective.name.text + name: text + norms: false + type: text + name: name + normalize: [] + original_fieldset: user + short: Short name or login of the user. + type: keyword + user.effective.roles: + dashed_name: user-effective-roles + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + flat_name: user.effective.roles + ignore_above: 1024 + level: extended + name: roles + normalize: + - array + original_fieldset: user + short: Array of user roles at the time of the event. + type: keyword user.email: dashed_name: user-email description: User email address. @@ -9657,10 +9921,145 @@ user: - array short: Array of user roles at the time of the event. type: keyword + user.target.domain: + dashed_name: user-target-domain + description: 'Name of the directory the user is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.target.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: user + short: Name of the directory the user is a member of. + type: keyword + user.target.email: + dashed_name: user-target-email + description: User email address. + flat_name: user.target.email + ignore_above: 1024 + level: extended + name: email + normalize: [] + original_fieldset: user + short: User email address. + type: keyword + user.target.full_name: + dashed_name: user-target-full-name + description: User's full name, if available. + example: Albert Einstein + flat_name: user.target.full_name + ignore_above: 1024 + level: extended + multi_fields: + - flat_name: user.target.full_name.text + name: text + norms: false + type: text + name: full_name + normalize: [] + original_fieldset: user + short: User's full name, if available. + type: keyword + user.target.group.domain: + dashed_name: user-target-group-domain + description: 'Name of the directory the group is a member of. + + For example, an LDAP or Active Directory domain name.' + flat_name: user.target.group.domain + ignore_above: 1024 + level: extended + name: domain + normalize: [] + original_fieldset: group + short: Name of the directory the group is a member of. + type: keyword + user.target.group.id: + dashed_name: user-target-group-id + description: Unique identifier for the group on the system/platform. + flat_name: user.target.group.id + ignore_above: 1024 + level: extended + name: id + normalize: [] + original_fieldset: group + short: Unique identifier for the group on the system/platform. + type: keyword + user.target.group.name: + dashed_name: user-target-group-name + description: Name of the group. + flat_name: user.target.group.name + ignore_above: 1024 + level: extended + name: name + normalize: [] + original_fieldset: group + short: Name of the group. + type: keyword + user.target.hash: + dashed_name: user-target-hash + description: 'Unique user hash to correlate information for a user in anonymized + form. + + Useful if `user.id` or `user.name` contain confidential information and cannot + be used.' + flat_name: user.target.hash + ignore_above: 1024 + level: extended + name: hash + normalize: [] + original_fieldset: user + short: Unique user hash to correlate information for a user in anonymized form. + type: keyword + user.target.id: + dashed_name: user-target-id + description: Unique identifier of the user. + flat_name: user.target.id + ignore_above: 1024 + level: core + name: id + normalize: [] + original_fieldset: user + short: Unique identifier of the user. + type: keyword + user.target.name: + dashed_name: user-target-name + description: Short name or login of the user. + example: albert + flat_name: user.target.name + ignore_above: 1024 + level: core + multi_fields: + - flat_name: user.target.name.text + name: text + norms: false + type: text + name: name + normalize: [] + original_fieldset: user + short: Short name or login of the user. + type: keyword + user.target.roles: + dashed_name: user-target-roles + description: Array of user roles at the time of the event. + example: '["kibana_admin", "reporting_user"]' + flat_name: user.target.roles + ignore_above: 1024 + level: extended + name: roles + normalize: + - array + original_fieldset: user + short: Array of user roles at the time of the event. + type: keyword group: 2 name: user nestings: + - user.changes + - user.effective - user.group + - user.target prefix: user. reusable: expected: @@ -9679,11 +10078,29 @@ user: - as: user at: source full: source.user + - as: target + at: user + full: user.target + - as: effective + at: user + full: user.effective + - as: changes + at: user + full: user.changes top_level: true reused_here: - full: user.group schema_name: group short: User's group relevant to the event. + - full: user.target + schema_name: user + short: Fields to describe the user relevant to the event. + - full: user.effective + schema_name: user + short: Fields to describe the user relevant to the event. + - full: user.changes + schema_name: user + short: Fields to describe the user relevant to the event. short: Fields to describe the user relevant to the event. title: User type: group diff --git a/generated/elasticsearch/6/template.json b/generated/elasticsearch/6/template.json index c597a6d2cb..50d69c8481 100644 --- a/generated/elasticsearch/6/template.json +++ b/generated/elasticsearch/6/template.json @@ -3045,10 +3045,130 @@ }, "user": { "properties": { + "changes": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "email": { + "ignore_above": 1024, + "type": "keyword" + }, + "full_name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "group": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, + "hash": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "roles": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, "domain": { "ignore_above": 1024, "type": "keyword" }, + "effective": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "email": { + "ignore_above": 1024, + "type": "keyword" + }, + "full_name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "group": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, + "hash": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "roles": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, "email": { "ignore_above": 1024, "type": "keyword" @@ -3100,6 +3220,66 @@ "roles": { "ignore_above": 1024, "type": "keyword" + }, + "target": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "email": { + "ignore_above": 1024, + "type": "keyword" + }, + "full_name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "group": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, + "hash": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "roles": { + "ignore_above": 1024, + "type": "keyword" + } + } } } }, diff --git a/generated/elasticsearch/7/template.json b/generated/elasticsearch/7/template.json index 63c8c381c8..b83ba4b038 100644 --- a/generated/elasticsearch/7/template.json +++ b/generated/elasticsearch/7/template.json @@ -3044,10 +3044,130 @@ }, "user": { "properties": { + "changes": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "email": { + "ignore_above": 1024, + "type": "keyword" + }, + "full_name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "group": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, + "hash": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "roles": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, "domain": { "ignore_above": 1024, "type": "keyword" }, + "effective": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "email": { + "ignore_above": 1024, + "type": "keyword" + }, + "full_name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "group": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, + "hash": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "roles": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, "email": { "ignore_above": 1024, "type": "keyword" @@ -3099,6 +3219,66 @@ "roles": { "ignore_above": 1024, "type": "keyword" + }, + "target": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "email": { + "ignore_above": 1024, + "type": "keyword" + }, + "full_name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "group": { + "properties": { + "domain": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "ignore_above": 1024, + "type": "keyword" + } + } + }, + "hash": { + "ignore_above": 1024, + "type": "keyword" + }, + "id": { + "ignore_above": 1024, + "type": "keyword" + }, + "name": { + "fields": { + "text": { + "norms": false, + "type": "text" + } + }, + "ignore_above": 1024, + "type": "keyword" + }, + "roles": { + "ignore_above": 1024, + "type": "keyword" + } + } } } }, diff --git a/schemas/user.yml b/schemas/user.yml index fa50676efd..ad4603ca90 100644 --- a/schemas/user.yml +++ b/schemas/user.yml @@ -18,6 +18,12 @@ - host - server - source + - at: user + as: target + - at: user + as: effective + - at: user + as: changes type: group fields: From c124d82cb514a4bab545e6a92bcaf2480ea3de1a Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 30 Oct 2020 16:29:59 -0400 Subject: [PATCH 02/17] WIP transferring a lot of the RFC explanations to a new user usage page --- docs/field-details.asciidoc | 8 + docs/usage/user.asciidoc | 287 ++++++++++++++++++++++++++++++++++++ 2 files changed, 295 insertions(+) create mode 100644 docs/usage/user.asciidoc diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index 56f63004b0..3bf25effc7 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -6441,6 +6441,10 @@ The user fields describe information about the user that is relevant to the even Fields can have one entry or multiple entries. If a user has more than one id, provide an array that includes all of them. +Find additional usage and examples in the user fields <> section. + + + [discrete] ==== User Field Details @@ -6609,6 +6613,10 @@ Note also that the `user` fields may be used directly at the root of the events. |===== + + +include::usage/user.asciidoc[] + [[ecs-user_agent]] === User agent Fields diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc new file mode 100644 index 0000000000..b5f443fb87 --- /dev/null +++ b/docs/usage/user.asciidoc @@ -0,0 +1,287 @@ +[[ecs-user-usage]] +==== Usage + +[discrete] +===== Categorization + +TODO - Discuss IAM categories, and I think that's it + +[discrete] +===== Field reuse + +The user fields can be reused in many places across ECS. This makes +it possible to capture many users relevant to a single event. + +Here's the full list of places where the user fields can appear: + +* `user.*` +* `user.effective.*` +* `user.target.*` +* `user.changes.*` +* `source.user.*` +* `destination.user.*` +* `client.user.*` +* `server.user.*` +* `host.user.*` (deprecated) + +Let's go over the meaning of each. + +The examples below will only populate `user.name` and sometimes `user.id` inside +the various `user` nestings, for readability. +However in implementations, unless otherwise noted, all `user` fields that can +reasonably be populated in each location should be populated. + +[discrete] +====== User fields at the Root of an Event + +The user fields at the root of an event must be used to capture the user +performing the main action described by the event. This is especially important +when there's more than one user present on the event. `user.*` fields at the root +of the event represent the user performing the action. + +In many cases, events that only mention one user should populate the user fields +at the root of the event, even if the user is not the one performing the action. + +In cases where a purpose-specific user field such as `url.username` is populated, +`user.name` should also be populated with the same user name. + +[source,json] +----------- +{ + "url": { "username": "alice" }, + "user": { "name": "alice" }, + "related": { "user": ["alice"] } +} +----------- + +[discrete] +====== Remote Logons + +When users are crossing host boundaries, the users are captured at +`source.user` and `destination.user`. + +Examples of data sources where this is applicable: + +* Remote logons via ssh, kerberos +* Firewalls observing network traffic + +In order to align with ECS' design of having `user` at the root of the event as the +user performing the action, all `source.user` fields should be copied to `user` at the root. + +Here's an example where user "alice" logs on to another host as user "deus": + +[source,json] +----------- +{ + "user": { + "name": "alice" + }, + "source": { + "user": { + "name": "alice" + }, + "ip": "10.42.42.42" + }, + "destination": { + "user": { + "name": "deus" + }, + "ip": "10.42.42.43" + }, + "related": { "user": ["alice", "deus"] } +} +----------- + +Whenever an event source populates the `client` and `server` fields in addition +to `source` and `destination`, the user fields should be copied accordingly as well. + +[discrete] +====== Privilege Changes + +The `user.effective` fields are relevant when there's a privilege escalation or demotion +and it's possible to determine the user requesting/performing the escalation. + +Use the `user` fields at the root to capture who is requesting the privilege change, +and `user.effective` to capture the requested privilege level, whether or not the +privilege change was successful. + +Here are examples where this is applicable: + +* A user changing identity on a host. + * Examples: sudo, su, Run as. +* Running a program as a different user. Examples: + * A trusted user runs a specific admin command as root via a mechanism such as the Posix setuid/setgid. + * A service manager with administrator privileges starts child processes as limited + users, for security purposes (e.g. root runs Apache HTTPD as user "apache") + +In cases where the event source only gives information about the effective user +and not who requested different privileges, the `user` fields at the root of the +event should be used instead. + +Here's an example of user "alice" running a command as root via sudo: + +[source,json] +----------- +{ + "user": { + "name": "alice", + "id": "1001", + "effective": { + "name": "root", + "id": "1" + } + }, + "related": { "user": ["alice", "root"] } +} +----------- + +When it's not possible (or it's prohibitive) to determine which user is requesting +different privilege levels, it's acceptable to capture the effective user at the +root of the event. Typically a privilege change event will already have happened, +for example: bob "su" as root; and subsequent events will show the root user +performing the actions. + +[discrete] +====== Identity and Access Management + +Whenever a user is performing an action that affects another user -- typically +in IAM scenarios -- the user affected by the action is captured at +`user.target`. The user performing the IAM activity is captured at the root +of the event. + +Examples of IAM activity include: + +* user-a creates or deletes user-b +* user-a modifies user-b + +In the create/delete scenarios, there's either no prior state (user creation) +or no post state (user deletion). In these cases, only `user` at the root and +`user.target` must be populated. + +Example where "root" creates user "bob": + +[source,json] +----------- +{ + "user": { + "name": "root", + "id": "1", + "target": { + "name": "bob", + "id": "1002", + ... + } + } + "related": { "user": ["bob", "root"] } +} +----------- + +When there's a change of state to an existing user, `user.target` must be used +to capture the prior state of the user, and `user.changes` should list only +the changes that were performed. + +Example where "root" renames user "bob" to "bob.barker": + +[source,json] +----------- +{ + "user": { + "name": "root", + "id": "1", + "target": { + "name": "bob", + "id": "1002" + }, + "changes": { + "name": "bob.barker" + } + }, + "related": { "user": ["bob", "bob.barker", "root"] } +} +----------- + +You'll note in the example above that unmodified attributes like the user ID are +not repeated under `user.changes.*`, since they didn't change. + +[discrete] +====== Combining IAM and Privilege Change + +We've covered above how `user.target` and `user.changes` can be used at the same time. +If privilege escalation is captured in the same IAM event, `user.effective` +should of course be used as well. + +Here's the "rename" example from the IAM section above. In the following example, +we know "alice" is escalating privileges as "root", in order to modify user "bob": + +[source,json] +----------- +{ + "user": { + "name": "alice", + "id": "1001", + "effective": { + "name": "root", + "id": "1" + }, + "target": { + "name": "bob", + "id": "1002" + }, + "changes": { + "name": "bob.barker" + } + }, + "related": { "user": ["alice", "bob", "bob.barker", "root"] } +} +----------- + +[discrete] +====== Notes about reuse within the "user" field set + +TODO + +[discrete] +===== Pivoting via related.user + +In all events in this page, we've populated the `related.user` fields. + +Any event that has users in it should always populate the array field `related.user` +with all usernames seen in the event, even if these user names were in custom fields. +Note that this field is not a nesting of all user fields, +it's a flat array meant to contain user identifiers. + +Taking the example from `user.changes` again, we can see that no matter the role +of the each user (before/after privilege escalation, affected user, username after rename), they are all present in `related.user`: + +[source,json] +----------- +{ + "user": { + "name": "alice", + "id": "1001", + "effective": { + "name": "root", + "id": "1" + }, + "target": { + "name": "bob", + "id": "1002" + }, + "changes": { + "name": "bob.barker" + } + }, + "related": { "user": ["alice", "root", "bob", "bob.barker"] } +} +----------- + +Like the other fields in the <> field set, `related.user` is meant to facilitate +pivoting. For example, if you have a suspicion about user "bob.barker", searching +for this name in `related.user` will give you all events related to this user, whether +it's the creation / rename of the user, or events where this user was active in a system. + +[discrete] +===== Mapping Examples + +For examples of mapping events from various sources, you can look at +https://github.com/elastic/ecs/blob/master/rfcs/text/0007-multiple-users.md#source-data[RFC 0007 in section Source Data]. From 613a5254943cafc40934600bb59ef440fef2adf2 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 30 Oct 2020 16:42:55 -0400 Subject: [PATCH 03/17] Changelog --- CHANGELOG.next.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index c05fd1c2f7..a2da070130 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -18,11 +18,15 @@ Thanks, you're awesome :-) --> * Added `event.category` "registry". #1040 * Added `event.category` "session". #1049 +* Added usage documentation for `user` fields. #1066 +* Added `user` fields at `user.effective.*`, `user.target.*` and `user.changes.*`. #1066 #### Improvements #### Deprecated +* Deprecated `host.user.*` fields for removal at the next major. #1066 + ### Tooling and Artifact Changes #### Breaking changes From 6906487935e4196f280866c4d5804cf9ed9c8006 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 2 Nov 2020 14:42:02 -0500 Subject: [PATCH 04/17] Section on categorizing IAM activity --- docs/usage/user.asciidoc | 62 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 2 deletions(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index b5f443fb87..4d086ffceb 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -4,12 +4,70 @@ [discrete] ===== Categorization -TODO - Discuss IAM categories, and I think that's it +User fields can be present in any kind of event, without affecting the event's +categorization. + +However when the event is about IAM (Identity and Account Management), +make sure you categorize it as follows. In this section we'll cover specifically +`event.category` and `event.type` with regards to IAM activity. Make sure to read +the <> to see all allowed +values, and read more about `event.kind` and `event.outcome`. + +NOTE: IAM activity is a bit particular in that events are expected to be assigned 2 event types. +One of them indicates the type of activity (creation, deletion, change, etc.), +and the other indicates whether a user or a group is the target of the management activity. + +Many sections of the documents are elided, in order to focus on the categorization +of the events. + +Creation of group "test-group": + +```JSON +{ + "event": { + "kind": "event", + "category": ["iam"], <1> + "type": ["group", "creation"], <2> + "outcome": "success" + }, + "group": { "name": "test-group", ... }, + "user": { ... }, + "related": { "user": [ ... ] } +} +``` +<1> Category "iam" +<2> Both relevant event types to a group creation + +Adding "test-user" to "test-group": + +```JSON +{ + "event": { + "kind": "event", + "category": ["iam"], <1> + "type": ["user", "change"], <2> + "action": "user added to group", <3> + "outcome": "success" + }, + "user": { + ... + "target": { <4> + "name": "test-user", + "group": { "name": "test-group" } + } + }, + "related": { "user": [ ... ] } +} +``` +<1> Category "iam" +<2> Both relevant event types to a user modification +<3> `event.action` is not a categorization field, and has no mandated value. It can be populated based on source event details or by a pipeline, to ensure the event captures all subtleties of what's happening. +<4> How to use all possible user fields is detailed below. [discrete] ===== Field reuse -The user fields can be reused in many places across ECS. This makes +The user fields can be reused (or appear) in many places across ECS. This makes it possible to capture many users relevant to a single event. Here's the full list of places where the user fields can appear: From 6d805b6d2256207744bb52205feefe67d072c033 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 2 Nov 2020 15:15:29 -0500 Subject: [PATCH 05/17] Add a TOC to the page --- docs/usage/user.asciidoc | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 4d086ffceb..02bf54a0c2 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -1,7 +1,24 @@ [[ecs-user-usage]] ==== Usage +Here are the subjects covered in this page. + +* <> + +* <>, or all places user fields can appear +** <> +** <> +** <> +** <> +** <> +** <> + +* <> + +* <> + [discrete] +[[ecs-user-usage-categorization]] ===== Categorization User fields can be present in any kind of event, without affecting the event's @@ -65,6 +82,7 @@ Adding "test-user" to "test-group": <4> How to use all possible user fields is detailed below. [discrete] +[[ecs-user-usage-field-reuse]] ===== Field reuse The user fields can be reused (or appear) in many places across ECS. This makes @@ -90,6 +108,7 @@ However in implementations, unless otherwise noted, all `user` fields that can reasonably be populated in each location should be populated. [discrete] +[[ecs-user-usage-user-at-root]] ====== User fields at the Root of an Event The user fields at the root of an event must be used to capture the user @@ -113,6 +132,7 @@ In cases where a purpose-specific user field such as `url.username` is populated ----------- [discrete] +[[ecs-user-usage-remote-logons]] ====== Remote Logons When users are crossing host boundaries, the users are captured at @@ -154,6 +174,7 @@ Whenever an event source populates the `client` and `server` fields in addition to `source` and `destination`, the user fields should be copied accordingly as well. [discrete] +[[ecs-user-usage-privilege-changes]] ====== Privilege Changes The `user.effective` fields are relevant when there's a privilege escalation or demotion @@ -200,6 +221,7 @@ for example: bob "su" as root; and subsequent events will show the root user performing the actions. [discrete] +[[ecs-user-usage-iam]] ====== Identity and Access Management Whenever a user is performing an action that affects another user -- typically @@ -262,6 +284,7 @@ You'll note in the example above that unmodified attributes like the user ID are not repeated under `user.changes.*`, since they didn't change. [discrete] +[[ecs-user-usage-combining]] ====== Combining IAM and Privilege Change We've covered above how `user.target` and `user.changes` can be used at the same time. @@ -294,17 +317,19 @@ we know "alice" is escalating privileges as "root", in order to modify user "bob ----------- [discrete] +[[ecs-user-usage-reuse-within]] ====== Notes about reuse within the "user" field set TODO [discrete] +[[ecs-user-usage-pivoting]] ===== Pivoting via related.user In all events in this page, we've populated the `related.user` fields. Any event that has users in it should always populate the array field `related.user` -with all usernames seen in the event, even if these user names were in custom fields. +with all usernames seen in the event; including event names that appear in custom fields. Note that this field is not a nesting of all user fields, it's a flat array meant to contain user identifiers. @@ -339,6 +364,7 @@ for this name in `related.user` will give you all events related to this user, w it's the creation / rename of the user, or events where this user was active in a system. [discrete] +[[ecs-user-usage-mappings]] ===== Mapping Examples For examples of mapping events from various sources, you can look at From 4efecc9afbd048602bae6250b91977ebf0e0b80d Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 2 Nov 2020 15:41:36 -0500 Subject: [PATCH 06/17] Subtleties around field reuse --- docs/usage/user.asciidoc | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 02bf54a0c2..b5cd85aed2 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -11,7 +11,7 @@ Here are the subjects covered in this page. ** <> ** <> ** <> -** <> +** <> * <> @@ -317,10 +317,24 @@ we know "alice" is escalating privileges as "root", in order to modify user "bob ----------- [discrete] -[[ecs-user-usage-reuse-within]] -====== Notes about reuse within the "user" field set +[[ecs-user-usage-reuse-subtleties]] +====== Subtleties around field reuse -TODO +Most cases of field reuse in ECS are reusing a field set inside another field set. +Two examples of this are: + +* reusing `group` in `user`, resulting in the `user.group.*` fields, or +* reusing `user` in `destination`, resulting in the `destination.user.*` fields, + which include `destination.user.group.*`. + +The `user` fields can also be reused within `user` as different names, +representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. + +It's important to note, that contrary to the `group` fields, +the user fields reused within `user` are **not** carried around when reusing `user` +in other places. To continue with the `destination` example, while `group` fields +are carried to `destination.user.group.*`, there are no `destination.user.effective.*`, +`destination.user.target.*` nor `destination.user.changes.*` fields. [discrete] [[ecs-user-usage-pivoting]] From 0f247f2bee7a093350143439397ec12fe24a09b2 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 2 Nov 2020 15:41:51 -0500 Subject: [PATCH 07/17] Deprecation of host.user.* --- docs/usage/user.asciidoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index b5cd85aed2..c0fbc7f2f1 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -17,6 +17,8 @@ Here are the subjects covered in this page. * <> +* <> + [discrete] [[ecs-user-usage-categorization]] ===== Categorization @@ -383,3 +385,10 @@ it's the creation / rename of the user, or events where this user was active in For examples of mapping events from various sources, you can look at https://github.com/elastic/ecs/blob/master/rfcs/text/0007-multiple-users.md#source-data[RFC 0007 in section Source Data]. + +[discrete] +[[ecs-user-usage-deprecations]] +===== Deprecations + +As of ECS 1.8, `host.user.*` fields are deprecated and will be removed at the next +major version of ECS. From 7002fe480d99994a6ba9362c824601b21943d8c4 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 2 Nov 2020 15:48:02 -0500 Subject: [PATCH 08/17] Additional callouts for one of the examples --- docs/usage/user.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index c0fbc7f2f1..31131c63ae 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -127,11 +127,13 @@ In cases where a purpose-specific user field such as `url.username` is populated [source,json] ----------- { - "url": { "username": "alice" }, - "user": { "name": "alice" }, + "url": { "username": "alice" }, <1> + "user": { "name": "alice" }, <2> "related": { "user": ["alice"] } } ----------- +<1> Purpose-specific username field +<2> Username copied to `user.name` to establish `user.name` as a reliable baseline. [discrete] [[ecs-user-usage-remote-logons]] From daafe57388f8e19ddc2c81c2b0283fcdcfe4d2ec Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 2 Nov 2020 16:23:08 -0500 Subject: [PATCH 09/17] Fix list nesting, improve wording in a few places --- docs/usage/user.asciidoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 31131c63ae..6ce401fd95 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -27,7 +27,7 @@ User fields can be present in any kind of event, without affecting the event's categorization. However when the event is about IAM (Identity and Account Management), -make sure you categorize it as follows. In this section we'll cover specifically +it should be categorized as follows. In this section we'll cover specifically `event.category` and `event.type` with regards to IAM activity. Make sure to read the <> to see all allowed values, and read more about `event.kind` and `event.outcome`. @@ -36,7 +36,7 @@ NOTE: IAM activity is a bit particular in that events are expected to be assigne One of them indicates the type of activity (creation, deletion, change, etc.), and the other indicates whether a user or a group is the target of the management activity. -Many sections of the documents are elided, in order to focus on the categorization +Many sections of the examples below are elided, in order to focus on the categorization of the events. Creation of group "test-group": @@ -100,7 +100,7 @@ Here's the full list of places where the user fields can appear: * `destination.user.*` * `client.user.*` * `server.user.*` -* `host.user.*` (deprecated) +* `host.user.*` (<>) Let's go over the meaning of each. @@ -113,7 +113,7 @@ reasonably be populated in each location should be populated. [[ecs-user-usage-user-at-root]] ====== User fields at the Root of an Event -The user fields at the root of an event must be used to capture the user +The user fields at the root of an event are used to capture the user performing the main action described by the event. This is especially important when there's more than one user present on the event. `user.*` fields at the root of the event represent the user performing the action. @@ -191,10 +191,10 @@ privilege change was successful. Here are examples where this is applicable: * A user changing identity on a host. - * Examples: sudo, su, Run as. +** Examples: sudo, su, Run as. * Running a program as a different user. Examples: - * A trusted user runs a specific admin command as root via a mechanism such as the Posix setuid/setgid. - * A service manager with administrator privileges starts child processes as limited +** A trusted user runs a specific admin command as root via a mechanism such as the Posix setuid/setgid. +** A service manager with administrator privileges starts child processes as limited users, for security purposes (e.g. root runs Apache HTTPD as user "apache") In cases where the event source only gives information about the effective user @@ -292,7 +292,7 @@ not repeated under `user.changes.*`, since they didn't change. ====== Combining IAM and Privilege Change We've covered above how `user.target` and `user.changes` can be used at the same time. -If privilege escalation is captured in the same IAM event, `user.effective` +If privilege escalation is also present in the same IAM event, `user.effective` should of course be used as well. Here's the "rename" example from the IAM section above. In the following example, @@ -329,7 +329,7 @@ Two examples of this are: * reusing `group` in `user`, resulting in the `user.group.*` fields, or * reusing `user` in `destination`, resulting in the `destination.user.*` fields, - which include `destination.user.group.*`. + which also include `destination.user.group.*`. The `user` fields can also be reused within `user` as different names, representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. From 63b203f8070b7634fee59961056927f1916ee466 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 6 Nov 2020 08:28:55 -0500 Subject: [PATCH 10/17] escalate "to" Co-authored-by: Eric Beahan --- docs/usage/user.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 6ce401fd95..0f21064589 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -296,7 +296,7 @@ If privilege escalation is also present in the same IAM event, `user.effective` should of course be used as well. Here's the "rename" example from the IAM section above. In the following example, -we know "alice" is escalating privileges as "root", in order to modify user "bob": +we know "alice" is escalating privileges to "root", in order to modify user "bob": [source,json] ----------- From 65e534b8dac36a2a6d057a16f6ea6cff41aa58a9 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 6 Nov 2020 08:28:28 -0500 Subject: [PATCH 11/17] Root uid is zeero --- rfcs/text/0007-multiple-users.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/rfcs/text/0007-multiple-users.md b/rfcs/text/0007-multiple-users.md index 9403eecb0a..a774cb44bf 100644 --- a/rfcs/text/0007-multiple-users.md +++ b/rfcs/text/0007-multiple-users.md @@ -152,7 +152,7 @@ Here's an example of user "alice" running a command as root via sudo: "id": "1001", "effective": { "name": "root", - "id": "1" + "id": "0" } } } @@ -186,7 +186,7 @@ Example where "root" creates user "bob": { "user": { "name": "root", - "id": "1", + "id": "0", "target": { "name": "bob", "id": "1002", @@ -206,7 +206,7 @@ Example where "root" renames user "bob" to "bob.barker": { "user": { "name": "root", - "id": "1", + "id": "0", "target": { "name": "bob", "id": "1002" @@ -237,7 +237,7 @@ we know "alice" is escalating privileges as "root", in order to modify user "bob "id": "1001", "effective": { "name": "root", - "id": "1" + "id": "0" }, "target": { "name": "bob", @@ -266,7 +266,7 @@ the event now looks like: "id": "1001", "effective": { "name": "root", - "id": "1" + "id": "0" }, "target": { "name": "bob", From f82ba409512332f6f5b95c61e4ff8eec68cc0239 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 6 Nov 2020 08:35:14 -0500 Subject: [PATCH 12/17] Clarify instead of what Co-authored-by: Eric Beahan --- docs/usage/user.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 0f21064589..3ca62ce1f4 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -199,7 +199,7 @@ Here are examples where this is applicable: In cases where the event source only gives information about the effective user and not who requested different privileges, the `user` fields at the root of the -event should be used instead. +event should be used instead of `user.effective`. Here's an example of user "alice" running a command as root via sudo: From 459976e857fa900b467dd64f67afc2701563a9ba Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Wed, 11 Nov 2020 10:59:43 -0500 Subject: [PATCH 13/17] Add a short section on user identifier gotchas. --- docs/usage/user.asciidoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 3ca62ce1f4..82ac4ff296 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -4,6 +4,7 @@ Here are the subjects covered in this page. * <> +* <> * <>, or all places user fields can appear ** <> @@ -83,6 +84,18 @@ Adding "test-user" to "test-group": <3> `event.action` is not a categorization field, and has no mandated value. It can be populated based on source event details or by a pipeline, to ensure the event captures all subtleties of what's happening. <4> How to use all possible user fields is detailed below. +[discrete] +[[ecs-user-identifiers]] +===== User identifiers + +Different systems use different values for user identifiers. Here are a few pointers +to help normalize some simple cases. + +* When a system provides a composite value for the user name (e.g. DOMAINNAME\username), + capture the domain name in `user.domain` and the user name (without the domain) in `user.name`. +* When a system uses an email address as the main identifier, populate both + `user.id` and `user.email` with it. + [discrete] [[ecs-user-usage-field-reuse]] ===== Field reuse From 7c3b29979a6b4e1d1ee69ef8ce9bfc91a99d9715 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Wed, 11 Nov 2020 16:05:24 -0500 Subject: [PATCH 14/17] Another attempt at explaining the self-reuse subtleties. This section still makes me cry a little! --- docs/usage/user.asciidoc | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index 82ac4ff296..b6f646385f 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -337,7 +337,7 @@ we know "alice" is escalating privileges to "root", in order to modify user "bob [[ecs-user-usage-reuse-subtleties]] ====== Subtleties around field reuse -Most cases of field reuse in ECS are reusing a field set inside another field set. +Most cases of field reuse in ECS are reusing a field set inside a different field set. Two examples of this are: * reusing `group` in `user`, resulting in the `user.group.*` fields, or @@ -345,13 +345,30 @@ Two examples of this are: which also include `destination.user.group.*`. The `user` fields can also be reused within `user` as different names, -representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. +representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. However it's important to note that `user` fields reused within +`user` are _not carried around anywhere else_. +Let's illustrate the various permutations of what's valid and what is not. + +[options="header"] +|===== +| Field | Validity | Notes + +| `user.group.*` | Valid | Normal reuse. +| `destination.user.group.*` | Valid | The `group` reuse gets carried around when `user` is reused elsewhere. +Populate only if relevant to the event. + +| `user.target.group.*`, `user.effective.group.*`, `user.changes.group.*` +| Valid +| The `group` reuse gets carried around even when `user` is reused within itself. +Populate only if relevant to the event. + +| `destination.user.target.*`, `destination.user.effective.*`, `destination.user.changes.*` +| *Invalid* +| The `user` fields reused within `user` are not carried around anywhere else. +The same rule applies when `user` is reused under `source`, `client` and `server`. + +|===== -It's important to note, that contrary to the `group` fields, -the user fields reused within `user` are **not** carried around when reusing `user` -in other places. To continue with the `destination` example, while `group` fields -are carried to `destination.user.group.*`, there are no `destination.user.effective.*`, -`destination.user.target.*` nor `destination.user.changes.*` fields. [discrete] [[ecs-user-usage-pivoting]] From dbef7218d27d01152e88ba5d7db91f235d17960c Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 23 Nov 2020 16:51:52 -0500 Subject: [PATCH 15/17] Introduce the 'beta' markers for the new 'user' field reuses --- docs/field-details.asciidoc | 15 +++++++++------ experimental/generated/ecs/ecs_nested.yml | 12 +++++++++--- generated/ecs/ecs_nested.yml | 12 +++++++++--- schemas/user.yml | 3 +++ 4 files changed, 30 insertions(+), 12 deletions(-) diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc index ffc1cad683..c9988b460f 100644 --- a/docs/field-details.asciidoc +++ b/docs/field-details.asciidoc @@ -6604,14 +6604,16 @@ Note also that the `user` fields may be used directly at the root of the events. // =============================================================== -| <> -| Fields to describe the user relevant to the event. +| <>| beta:[ Reusing the user fields in this location is currently considered beta.] + +Fields to describe the user relevant to the event. // =============================================================== -| <> -| Fields to describe the user relevant to the event. +| <>| beta:[ Reusing the user fields in this location is currently considered beta.] + +Fields to describe the user relevant to the event. // =============================================================== @@ -6622,8 +6624,9 @@ Note also that the `user` fields may be used directly at the root of the events. // =============================================================== -| <> -| Fields to describe the user relevant to the event. +| <>| beta:[ Reusing the user fields in this location is currently considered beta.] + +Fields to describe the user relevant to the event. // =============================================================== diff --git a/experimental/generated/ecs/ecs_nested.yml b/experimental/generated/ecs/ecs_nested.yml index 977a5c2232..77fe5f53e4 100644 --- a/experimental/generated/ecs/ecs_nested.yml +++ b/experimental/generated/ecs/ecs_nested.yml @@ -10034,25 +10034,31 @@ user: full: source.user - as: target at: user + beta: Reusing the user fields in this location is currently considered beta. full: user.target - as: effective at: user + beta: Reusing the user fields in this location is currently considered beta. full: user.effective - as: changes at: user + beta: Reusing the user fields in this location is currently considered beta. full: user.changes top_level: true reused_here: - full: user.group schema_name: group short: User's group relevant to the event. - - full: user.target + - beta: Reusing the user fields in this location is currently considered beta. + full: user.target schema_name: user short: Fields to describe the user relevant to the event. - - full: user.effective + - beta: Reusing the user fields in this location is currently considered beta. + full: user.effective schema_name: user short: Fields to describe the user relevant to the event. - - full: user.changes + - beta: Reusing the user fields in this location is currently considered beta. + full: user.changes schema_name: user short: Fields to describe the user relevant to the event. short: Fields to describe the user relevant to the event. diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml index bc126b3f0c..eb52906f88 100644 --- a/generated/ecs/ecs_nested.yml +++ b/generated/ecs/ecs_nested.yml @@ -10139,25 +10139,31 @@ user: full: source.user - as: target at: user + beta: Reusing the user fields in this location is currently considered beta. full: user.target - as: effective at: user + beta: Reusing the user fields in this location is currently considered beta. full: user.effective - as: changes at: user + beta: Reusing the user fields in this location is currently considered beta. full: user.changes top_level: true reused_here: - full: user.group schema_name: group short: User's group relevant to the event. - - full: user.target + - beta: Reusing the user fields in this location is currently considered beta. + full: user.target schema_name: user short: Fields to describe the user relevant to the event. - - full: user.effective + - beta: Reusing the user fields in this location is currently considered beta. + full: user.effective schema_name: user short: Fields to describe the user relevant to the event. - - full: user.changes + - beta: Reusing the user fields in this location is currently considered beta. + full: user.changes schema_name: user short: Fields to describe the user relevant to the event. short: Fields to describe the user relevant to the event. diff --git a/schemas/user.yml b/schemas/user.yml index ad4603ca90..8625f05897 100644 --- a/schemas/user.yml +++ b/schemas/user.yml @@ -20,10 +20,13 @@ - source - at: user as: target + beta: Reusing the user fields in this location is currently considered beta. - at: user as: effective + beta: Reusing the user fields in this location is currently considered beta. - at: user as: changes + beta: Reusing the user fields in this location is currently considered beta. type: group fields: From e573f8ed649bd338684b8bd8082b0e23554b1190 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 4 Dec 2020 14:49:13 -0500 Subject: [PATCH 16/17] Break a paragraph in two, to make sure that second part stands out Co-authored-by: Eric Beahan --- docs/usage/user.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index b6f646385f..d500f87e30 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -345,7 +345,9 @@ Two examples of this are: which also include `destination.user.group.*`. The `user` fields can also be reused within `user` as different names, -representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. However it's important to note that `user` fields reused within +representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. + +However, it's important to note that `user` fields reused within `user` are _not carried around anywhere else_. Let's illustrate the various permutations of what's valid and what is not. From 94cac002465a2a352d89decdfe4ec0d295795be8 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Fri, 4 Dec 2020 15:04:19 -0500 Subject: [PATCH 17/17] Link to 'Mapping Network Events' page, as suggested in review --- docs/usage/user.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/usage/user.asciidoc b/docs/usage/user.asciidoc index d500f87e30..f1a7452af9 100644 --- a/docs/usage/user.asciidoc +++ b/docs/usage/user.asciidoc @@ -189,6 +189,8 @@ Here's an example where user "alice" logs on to another host as user "deus": Whenever an event source populates the `client` and `server` fields in addition to `source` and `destination`, the user fields should be copied accordingly as well. +You can review <> to learn more about +mapping network events. [discrete] [[ecs-user-usage-privilege-changes]] @@ -345,7 +347,7 @@ Two examples of this are: which also include `destination.user.group.*`. The `user` fields can also be reused within `user` as different names, -representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. +representing the role of each relevant user. Examples are the `user.target.*` or `user.effective.*` fields. However, it's important to note that `user` fields reused within `user` are _not carried around anywhere else_.