From d6714a0dd431d97040869f78b19146e1b6900aca Mon Sep 17 00:00:00 2001 From: Dain Perkins Date: Mon, 17 Aug 2020 08:30:43 -0400 Subject: [PATCH 01/13] Updated Session rfc (stage 2) Revised verbage in description and promioted RFC to draft --- rfcs/text/0004-session.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/rfcs/text/0004-session.md b/rfcs/text/0004-session.md index 2617ea441c..7fa92f2ffd 100644 --- a/rfcs/text/0004-session.md +++ b/rfcs/text/0004-session.md @@ -1,8 +1,8 @@ # 0004: Session -- Stage: **0 (strawperson)** -- Date: 7/30/2020 +- Stage: **2 (draft)** +- Date: 8/17/2020 - Stage: **2 (draft)** -- Date: 8/17/2020 +- Date: TBD * Stage 0: https://github.com/elastic/ecs/pull/879 +* Stage 1: https://github.com/elastic/ecs/pull/935 diff --git a/rfcs/text/0004/session.yml b/rfcs/text/0004/session.yml new file mode 100644 index 0000000000..495e34dbcc --- /dev/null +++ b/rfcs/text/0004/session.yml @@ -0,0 +1,57 @@ +--- +- name: session + title: Session + group: 2 + short: User, admin, application, network, or service sessions + description: |- + These fields are used to track an entity's interaction with various assets, services, and applications in an enterprise. Sessions will typically include a start event, often a login / authorization event performed locally or via network based mechanisms, and an end event indicating a logoff or session termination. Related events during the scope of the session will typically be associated via tuples of user, source and or destination ip/port, or cookies. + + When available, event start/end or duration fields should be populated, as well as iam, user, network, host, observer, process, source, destination, client, and server fields as appropriate to describe the specifics of the interaction. + + type: group + + fields: + + - name: kind + level: extended + type: keyword + short: Session kind + description: > + Session kind describes the type of access represented - system (e.g. local/remote/virtual system logins to workstations, servers, appliances, etc.), application (e.g. web, ftp, database interactions), or network (VPN connections, 802.1x or NAC access to network, wireless WPA sessions). + + example: network + + - name: type + level: extended + type: Logical session type + short: Session type + description: > + Session type fields provide additional detail on the scope of the interactions being tracked. Initial values include local (e.g. hands on keyboard, serial connections, etc.), remote (e.g. direct system access via remote desktop, ssh, etc), virtual (e.g. VDI, VDA, etc.), and wired, wireless and vpn network connections. Session type allows arrays to provide, if necessary, multiple values for a given interaction. + + example: wireless + normalize: + - array + + - name: authorization + level: extended + type: keyword + description: > + Authorization scope of the session. Initial values will include user (e.g. user vdi/vda, vpn, or web sessions, wired/wireless/vpn network access, etc), administrative sessions (root, VMWare Host access, router "enable" level cli, etc.) or service (e.g. network to network VPN, non-user verified application service sessions). + + example: user + + - name: name + level: extended + type: Session Name + description: The name field is meant to contain a locally significant identifier for the session as configured. This could represent a VPN group name, a wireless network name (ssid), a wired network segment, VDI service name, service or application identifier. + + example: HQ-Wireless + + - name: id + level: extended + type: Session id + description: > + The id field is meant to contain a locally significant identifier for the session as provided by the observer or host reporting the session. If no id is provided this field can remain blank, or a hash function similar to network.community_id can be used to discretely identify sessions from unique values. + + example: 7635344 + From 983668c12b346fa705f6371985864b04728771ab Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 19 Oct 2020 16:00:07 -0400 Subject: [PATCH 08/13] Fix YAML format, try to make descriptions render well. --- rfcs/text/0004/session.yml | 74 ++++++++++++++++++++++++++------------ 1 file changed, 51 insertions(+), 23 deletions(-) diff --git a/rfcs/text/0004/session.yml b/rfcs/text/0004/session.yml index 495e34dbcc..f292ace015 100644 --- a/rfcs/text/0004/session.yml +++ b/rfcs/text/0004/session.yml @@ -2,56 +2,84 @@ - name: session title: Session group: 2 + type: group short: User, admin, application, network, or service sessions description: |- These fields are used to track an entity's interaction with various assets, services, and applications in an enterprise. Sessions will typically include a start event, often a login / authorization event performed locally or via network based mechanisms, and an end event indicating a logoff or session termination. Related events during the scope of the session will typically be associated via tuples of user, source and or destination ip/port, or cookies. When available, event start/end or duration fields should be populated, as well as iam, user, network, host, observer, process, source, destination, client, and server fields as appropriate to describe the specifics of the interaction. - type: group + fields: + + - name: kind + level: extended + type: keyword + short: Session kind (system, application or network). + description: > + Session kind describes the type of access represented. Acceptable values are: + "application", "system", and "network". - fields: + "application" is relevant for application-level sessions such as web, ftp, database. - - name: kind - level: extended - type: keyword - short: Session kind - description: > - Session kind describes the type of access represented - system (e.g. local/remote/virtual system logins to workstations, servers, appliances, etc.), application (e.g. web, ftp, database interactions), or network (VPN connections, 802.1x or NAC access to network, wireless WPA sessions). + "system" is relevant for sessions initiated by computer systems rather than humans. - example: network + "network" is relevant to describe various kinds of network-level sessions + (VPN, 802.1x, wireless WPA sessions, NAC access to network). + + example: network + + - name: type + level: extended + type: keyword + normalize: + - array + short: 'Session type (array of: local, remote, virtual, wired, wireless and/or vpn).' + description: > + Session type provides additional details on the scope of the interactions being tracked. Acceptable values are: "local", "remote", "virtual", "wired", "wireless", "vpn". - - name: type - level: extended - type: Logical session type - short: Session type - description: > - Session type fields provide additional detail on the scope of the interactions being tracked. Initial values include local (e.g. hands on keyboard, serial connections, etc.), remote (e.g. direct system access via remote desktop, ssh, etc), virtual (e.g. VDI, VDA, etc.), and wired, wireless and vpn network connections. Session type allows arrays to provide, if necessary, multiple values for a given interaction. + "local" is relevant e.g. for serial connections, physical sessions (hands on keyboard). - example: wireless - normalize: - - array + "remote" is relevant for any remote connection: direct system access via remote desktop, ssh, etc. + + "virtual" is for VDI, VDA, etc. + + (missing clarifications for: wired, wireless and vpn network connections?) + + Session type is an array field, to provide the ability to capture multiple applicable values for a given session. + + example: '["wireless"]' - name: authorization level: extended type: keyword + short: Authorization scope of the session (user, admin or service). description: > - Authorization scope of the session. Initial values will include user (e.g. user vdi/vda, vpn, or web sessions, wired/wireless/vpn network access, etc), administrative sessions (root, VMWare Host access, router "enable" level cli, etc.) or service (e.g. network to network VPN, non-user verified application service sessions). + Authorization scope of the session. Acceptable values are: "user", "admin" and "service". + + "user" should be used for web sessions, network access, user vdi/vda, vpn, wired/wireless/vpn, etc. + + "admin" should be used for administrative activity: root user, VMWare Host access, router "enable" level cli, etc. + + "service" should be used for network to network VPN, non-user verified application service sessions, etc. example: user - name: name level: extended - type: Session Name - description: The name field is meant to contain a locally significant identifier for the session as configured. This could represent a VPN group name, a wireless network name (ssid), a wired network segment, VDI service name, service or application identifier. + type: keyword + short: Session name as specified by this source. + description: The `session.name` field is meant to contain a locally significant textual identifier for the session as configured. This could represent a VPN group name, a wireless network name (ssid), a wired network segment, VDI service name, service or application identifier. example: HQ-Wireless - name: id level: extended - type: Session id + type: keyword + short: Session id or fingerprint. description: > - The id field is meant to contain a locally significant identifier for the session as provided by the observer or host reporting the session. If no id is provided this field can remain blank, or a hash function similar to network.community_id can be used to discretely identify sessions from unique values. + The id field is a locally significant identifier for the session as provided by the observer or host reporting the session. + + If no id is provided, this field can remain blank, or a fingerprint function similar to network.community_id can be used to discretely identify sessions from unique values. example: 7635344 From 71e62aa3da10652072deb8eb7461fdf5f69da856 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 19 Oct 2020 16:05:24 -0400 Subject: [PATCH 09/13] Try to reformat the examples... Not sure about my formatting of Example 1 section. --- rfcs/text/0004-session.md | 70 ++++++++++++++++++++++++--------------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/rfcs/text/0004-session.md b/rfcs/text/0004-session.md index 0339ee4c56..e694aab976 100644 --- a/rfcs/text/0004-session.md +++ b/rfcs/text/0004-session.md @@ -4,12 +4,11 @@ - Stage: **2 (draft)** - Date: TBD - +This RFC calls for the addition of session fields to describe events related to +various types of "sessions" reported by appliances, security devices, systems, +management portals, applications, etc. ## Fields -This RFC calls for the addition of session fields to describe events related to various types of "sessions" reported by appliances, security devices, systems, management portals, applications, etc. | Field | Description | | ----- | ----------- | @@ -59,44 +58,61 @@ Source data expectations include: - Web Server, WAF, or ADC logs (USer or cookie based web ession control) - APM telemetry -Example 1: Meraki 802.1x Logs (WLC) -* EAP session start) - * `<134>1 1580551704.928047208 my_AP events type=8021x_eap_success radio='1' vap='2' client_mac='12:34:56:78:9A:BC' client_ip='192.168.1.100' identity='JohnDoe' aid='1687088497’ +### Example 1: Meraki 802.1x Logs (WLC) + +EAP session start + +`<134>1 1580551704.928047208 my_AP events type=8021x_eap_success radio='1' vap='2' client_mac='12:34:56:78:9A:BC' client_ip='192.168.1.100' identity='JohnDoe' aid='1687088497'` 802.1x EAP De-association Message -* EAP session end - * `<134>1 1580551705.928047208 my_AP events type=8021x_deauth radio='1' vap='2' identity='JohnDoe' aid='1687088497’' -* Note, while there is an association id (session.id) created prior to wpa/802.1x authentication, building the session event from the eap success message allows for easier integration of fields like username, client.ip, etc. in an 802.1x or WPA environment +EAP session end + +`<134>1 1580551705.928047208 my_AP events type=8021x_deauth radio='1' vap='2' identity='JohnDoe' aid='1687088497'` + +Note, while there is an association id (session.id) created prior to wpa/802.1x authentication, building the session event from the eap success message allows for easier integration of fields like username, client.ip, etc. in an 802.1x or WPA environment. + +Base 802.11 Association: (802.11 session start) + +`<134>1 1380653443.857790533 MR18 events type=association radio='1' vap='1' channel='2' rssi='23' aid='1687088497'` + +Base 802.11 Deassociation Message (802.11 session end) + +`1380653443.857790533 my_AP events type=disassociation radio='1' vap='2' channel='6' reason='8' instigator='2' duration='11979.728000' auth_neg_dur='1380653443.85779053324000' last_auth_ago='5.074000' is_wpa='1' full_conn='1.597000' ip_resp='1.597000' ip_src='192.168.111.251' arp_resp='1.265000' arp_src='192.168.111.251' dns_server='192.168.111.1' dns_req_rtt='1380653443.85779053335000' dns_resp='1.316000' aid='1813578850'` - * Base 802.11 Association: (802.11 session start) - * `<134>1 1380653443.857790533 MR18 events type=association radio='1' vap='1' channel='2' rssi='23' aid='1687088497’ - * Base 802.11 Deassociation Message (802.11 session end) - * `1380653443.857790533 my_AP events type=disassociation radio='1' vap='2' channel='6' reason='8' instigator='2' duration='11979.728000' auth_neg_dur='1380653443.85779053324000' last_auth_ago='5.074000' is_wpa='1' full_conn='1.597000' ip_resp='1.597000' ip_src='192.168.111.251' arp_resp='1.265000' arp_src='192.168.111.251' dns_server='192.168.111.1' dns_req_rtt='1380653443.85779053335000' dns_resp='1.316000' aid='1813578850' +### Example 2: ASA Admin Login +Session start -Example 2: ASA Admin Login -* Session start - * `<166>Feb 03 2020 11:27:05 5508x-1_9.12(3): %ASA-6-605005: Login permitted from 192.168.1.250/59277 to management:192.168.1.10/ssh for user "JohnDoe" -* Session End - * `<166>Feb 03 2020 11:27:05 5508x-1_9.12(3): %ASA-6-315011: SSH session from 192.168.1.250 on interface management for user JohnDoe disconnected by SSH server, reason: timeout +`<166>Feb 03 2020 11:27:05 5508x-1_9.12(3): %ASA-6-605005: Login permitted from 192.168.1.250/59277 to management:192.168.1.10/ssh for user "JohnDoe"` -Example 3: ASA Web VPN -* Session Start - * `<166>Feb 03 2020 11:27:05 5508x-1_9.12(3): %ASA-6-721016: WebVPN session for client user JohnDoe , 192.168.1.100 has been created. +Session End -* Session End: - * `<166>Feb 03 2020 11:27:05 5508x-1_9.12(3):%ASA-6-721018: WebVPN session for client user JohnDoe , IP 192.168.1.100 has been deleted. +`<166>Feb 03 2020 11:27:05 5508x-1_9.12(3): %ASA-6-315011: SSH session from 192.168.1.250 on interface management for user JohnDoe disconnected by SSH server, reason: timeout` + +### Example 3: ASA Web VPN + +Session Start + +`<166>Feb 03 2020 11:27:05 5508x-1_9.12(3): %ASA-6-721016: WebVPN session for client user JohnDoe , 192.168.1.100 has been created.` + +Session End + +`<166>Feb 03 2020 11:27:05 5508x-1_9.12(3):%ASA-6-721018: WebVPN session for client user JohnDoe , IP 192.168.1.100 has been deleted.` + +### Example 4: (DB Connection?) -Example 4: (DB Connection?) * TBD -Example 5: (Web Session?) +### Example 5: (Web Session?) + * TBD -Example 6: (Cloud Admin Session?) +# Example 6: (Cloud Admin Session?) + * TBD + From c341ea3d83ecbfa10f4ab272d2e97c4486fdde5d Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 19 Oct 2020 16:07:46 -0400 Subject: [PATCH 10/13] event.category session --- rfcs/text/0004-session.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rfcs/text/0004-session.md b/rfcs/text/0004-session.md index e694aab976..3751287451 100644 --- a/rfcs/text/0004-session.md +++ b/rfcs/text/0004-session.md @@ -8,6 +8,10 @@ This RFC calls for the addition of session fields to describe events related to various types of "sessions" reported by appliances, security devices, systems, management portals, applications, etc. +In addition to these fields, a new `event.category` value of "session" should be added. +Any event that captures information about a session should include "session" in +the array field `event.category`. + ## Fields | Field | Description | From 848fffd3c7a06bc5cbe780f8509a0ab8fe81f22a Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 19 Oct 2020 16:32:57 -0400 Subject: [PATCH 11/13] Add a few contributors to the People section --- rfcs/text/0004-session.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rfcs/text/0004-session.md b/rfcs/text/0004-session.md index 3751287451..c3e60687f7 100644 --- a/rfcs/text/0004-session.md +++ b/rfcs/text/0004-session.md @@ -173,6 +173,10 @@ Stage 4: Identify at least one real-world, production-ready implementation that The following are the people that consulted on the contents of this RFC. * @DainPerkins | Author +* @rw-access | Subject matter expert +* @jonathan-buttner | Sponsor (Security) +* @cyrille-leclerc | Stakeholder (Observability) +* @webmat | Editor * Stage 0: https://github.com/elastic/ecs/pull/879 -* Stage 1: https://github.com/elastic/ecs/pull/935 +* Stage 2: https://github.com/elastic/ecs/pull/935 -- Stage: **2 (draft)** +- Stage: **2 (candidate)** - Date: TBD This RFC calls for the addition of session fields to describe events related to