Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Session RFC PR to move to Stage 2 (Draft) #935

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

[RFC] Session RFC PR to move to Stage 2 (Draft) #935

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
d6714a0
Updated Session rfc (stage 2)
dainperkins Aug 17, 2020
4c2a21d
Updated Session RFC kind/type
dainperkins Aug 28, 2020
9d1e57d
Updated session kind and type
dainperkins Sep 14, 2020
57fc786
Unset the merge date. We'll set when stage 1 merges.
Oct 19, 2020
0721f80
Link to stage 1 RFC
Oct 19, 2020
16d1b9d
Space. The final frontier.
Oct 19, 2020
c8cb020
Move YML field descriptions to a file under 0004/ directory
Oct 19, 2020
983668c
Fix YAML format, try to make descriptions render well.
Oct 19, 2020
71e62aa
Try to reformat the examples...
Oct 19, 2020
c341ea3
event.category session
Oct 19, 2020
848fffd
Add a few contributors to the People section
Oct 19, 2020
69c11c7
It's stage 2, not stage 1
Oct 19, 2020
94aa976
Update rfcs/text/0004-session.md
dainperkins Feb 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 74 additions & 96 deletions rfcs/text/0004-session.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,79 +1,29 @@
# 0004: Session
<!--^ The ECS team will assign a unique, contiguous RFC number upon merging the initial stage of this RFC, taking care not to conflict with other RFCs.-->

- Stage: **0 (strawperson)** <!-- Update to reflect target stage -->
- Date: 7/30/2020 <!-- Update to reflect date of most recent stage advancement -->
- Stage: **2 (candidate)** <!-- Update to reflect target stage -->
- Date: TBD <!-- Update to reflect date of most recent stage advancement -->

<!--
Stage 0: Provide a high level summary of the premise of these changes. Briefly describe the nature, purpose, and impact of the changes. ~2-5 sentences.
-->
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
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 |
| ----- | ----------- |
|session.kind: | local, remote, network
|session.authorization: | user, admin, service
|session.type: | system, virtual, application, wired, wireless, vpn
|session.kind: | system, application, network
|session.type: | [ local, remote, virtual, wired, wireless, vpn ]
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO kind vs type is really hard to reason about / remember. type would be more clear if it was named connection_type.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea, tho my brain says "local isn't a connection!" but maybe thats ok.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I've updated these a bit, was hoping to get some feedback before submitting updates. I'll try and get the revisions up in the near future

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I would say that local is a connection, connecting to local host is a connection, just within a single kernel.

|session.authorization: | user, admin, service, access
Comment on lines +19 to +21
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This compact table is a great way to visualize all of these values together.

I have a few questions:

The value "access" appears to have been dropped out of the values mentioned in the YAML description. Was this intentional? If so, please remove it from here. If it was not intentional, please add it back in the new YAML file at rfcs/text/0004/session.yml

I initially thought there was an overlap with values session.kind: network and session.type: remote. When adjusting the YAML file for readability it occurred to me that session.kind: network was likely more to identify network level sessions, rather than anything that happens over a network. In other words, a web cookie-based session would not use session.kind: network, but session.kind: application. Am I understanding this correctly?

However within the different values for session.type, I do wonder if there's overlap. It seems like "wired", "wireless" and "vpn" would always be accompanied by value "remote". Is this also how you see this? Note that this is not necessarily a problem. "local" vs "remote" could be useful when plotted against one another, whereas "wired", "wireless" & "vpn" could be useful to break down the kinds of "remote" session types.

One final overlap concern: I do think session.kind: system and session.authorization: service are almost entirely overlapping, aren't they? Should we get rid of one of them, or am I misunderstanding a subtlety?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One final overlap concern: I do think session.kind: system and session.authorization: service are almost entirely overlapping, aren't they? Should we get rid of one of them, or am I misunderstanding a subtlety?

I was trying to find discrete combinations that would uniquely identify logging into a system, and a service running with authentication/authorization included in the "session". It may be unnecessary (I'll look thru auditbeat service logs and see what they look like... could just be that a system service is not something that would typically be defined as a session (e.g. starting up a vpn connection on a pfsense linux firewall - presumably the vpn application logs would be sufficient)

The value "access" appears to have been dropped...

the revamp of the fields seems to lend itself more towards the entity being authorized - authentication would be a part of the overall session, but I don't think it makes sense as a specific session field. Basically the split becomes:

  • "user interactive session" (user logs in or connects to a service or application to use said service/app)
  • "admin interactive session"(user logs in to manage a service or application e.g. root, enable mode in cisco parlance)
  • "Network session" (user or system connects to a monitored network)

Not all of the type values will apply to every session.kind:
Session Kind:

  • System (full system access)
    • local (hands on keyboard)
    • remote (bash via ssh)
    • virtual (Citrix -virtual desktop)
  • Application
    • remote (e.g. web connection, smb share, ftp)
    • local (possible but I can't think of an example)
    • virtual (citrix published apps)
      -Network
    • wired (802.1x network session - e.g. time connected to the LAN)
    • wireless (802.1x network session - e.g. time connected to the WLAN)
    • vpn (user connects to vpn concentrator

I think this one could use some more input- I can see session.type having fixed single values (virtual implies remote), or using an array (vpn would be network & remote, published apps & citrix desktop would be virtual & remote, opening a virtualbox session locally could be local & virtual...)

Does that all make sense?

Wired & wireless however would typically not use remote as the session is for the local user or workstation directly connecting to the local network (as opposed to connecting to another entity over the network)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm actually wondering if virtual needs to be specifically identified... a "remote" "system" session will be telnet, ssh, rdp, or citrix... not sure the virtual type is necessary to split out rdp/citrix

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And service as an authorization could also make sense for workstation based network access (802.1x cert auth), network to network vpn, etc...

|session.name | locally relevant name if available (e.g. HQ Client VPN, Win19-VDI, FIN-EXCEL-vApp)
|session.id | session id provided by server or custom fingerprint



## Fields (yaml)
```yaml
---
- 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:
|session.id | session id provided by server or custom fingerprint of discrete identifiers

- name: kind
level: extended
type: keyword
short: Kind of session
description: > Session kind can be local (console, on the keyboard), remote (ssh, vdi, web, ftp), or network (802.1x, wpa, NAC)
Additional fields will be dependent on the specifics of the session reported.
See detailed field descriptions in [rfcs/text/0004/session.yml](0004/session.yml).

example: network

- name: authorization
level: extended
type: keyword
description: Authorization scope of the session. Initial values will include general user level access (e.g. user vdi/vda, vpn, or web sessions, network access, etc), administrative sessions (root, VMWare Host access, router cli, etc.) or service (network to network VPN, non-user verified services sessions e.g. micro-service backend architectures).

example: user

- name: type
level: extended
type: Logical session type
description: Session type describes the interaction/access provided. Initial values include system (shell or desktop), virtual (VDI), application (web, ftp, etc.), wired (nac, 802.1x), wireless (wpa/.1x), or vpn (ipsec, ssl, etc). Note that actual aaa mechanism (system, domain, wpa, 802.1x) does not indicate a specific session type.

example: wireless

- 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, 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
```
<!--
Stage: 1: Describe at a high level how this change affects fields. Which fieldsets will be impacted? How many fields overall? Are we primarily adding fields, removing fields, or changing existing fields? The goal here is to understand the fundamental technical implications and likely extent of these changes. ~2-5 sentences.
-->
Expand All @@ -88,62 +38,85 @@ Stage 3: Add or update all remaining field definitions. The list should now be e

## Usage

Session fields are used to describe the sesison attributes of:
- Client VPN Sessions
- Network to Network VPN Sessions
- Network Access Sessions (NAC, WPA, EAP, etc.)
- Local or remote device login sessions (RDP, ICA, xWindows)
Session fields are used to describe and track a discrete grouping of interactions, typically bounded by
authentication or authorization events and tied to a specific user, application, or system component.

For example:
- Network Access Sessions (NAC or Wireless LAN)
- Local or remote device login sessions (tty, console, ssh, RDP, ICA, xWindows, etc.)
- VPN Sessions (network to network, or client to network)
- Local or remote device login sessions (console, tty, RDP, ICA, xWindows, ssh, etc.)
- Administrative sessions on infrastructure devices
- Administrative sessions on cloud or application management portals
- Applications sessions (e.g. sql server odbc session, application access session)
- Applications sessions (e.g. sql server odbc session, web cookie based session, application access session)
- Cloud API access sessions


## Source data
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For each of the log examples in the "Source data" section, could you include a breakdown of expected values for the session fields of each log event?

E.g. the ASA login could be something like

  • session.kind: network
  • session.authorization: admin
  • session.type: [remote]

Not sure if one of the values in the ASA example is a session name or session id, but if so, list those as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah - probably wouldn't be a bad idea to fill in everything in some additional example.json file(s)?

Source data expectations include:
- Wireless Lan Controllers
- Security appliances
- Security appliances (e.g. fw, waf)
- Network admission control devices
- Radius / tacacs servers
- Application server logs
- Radius / tacacs servers (802.1x EAP/PEAP aaa)
- Application server logs (FTP, MySQL)
- Web Server, WAF, or ADC logs (USer or cookie based web ession control)
- APM telemetry
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For our RUM agent, running on client websites tracking browsing sessions, I can only see us setting session.kind and session.id. Would love feedback from the RFC authors on whether this makes sense.

CC @jahtalab

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the idea (only filling out relevant fields) makes total sense... tho in respect to this and the previous comment it makes me think I'm missing something that identifies a RUM type session (but then I also don't really know what other fields would be coming in that would make filtering results from a mixed index easy). Unauthenticated web sessions for instance would't need to use session.auth, but after a login could (along with user.name, etc.). I don't see that one as big a deal as e.g. network access logins (vpn, wireless, etc)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To add some context, the RUM sessions are not necessarily authenticated, even until they are complete, e.g. a user session for going through checkout.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jahtalab do we have any notion of auth no? AFAIK we don't, and it's unlikely given the extreme variety of auth methods.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@andrewvc , We don't detect authentication per se, but there's a configuration for customers to add the user (username, id, ..) in the RUM agent. We can assume the user is authenticated (with some method) but it doesn't have to be.


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to reformat all of the examples below. The section "example 1" is one where I'm not sure if I did a good job.

Are we missing an example above for "802.1x EAP De-association Message"? Or is this just another way of referencing the "EAP session end"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will check - I think I may have used EAP & 802.11 messages instead of picking one or the other


`<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’
### Example 2: ASA Admin Login
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we could mention "ssh" in the ASA section title as well, to make it stand out for folks looking for an ssh example?

Copy link
Contributor Author

@dainperkins dainperkins Oct 21, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure


* 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'
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"`

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
Session End

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.
`<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`

* 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 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

<!--
Stage 1: Provide a high-level description of example sources of data. This does not yet need to be a concrete example of a source document, but instead can simply describe a potential source (e.g. nginx access log). This will ultimately be fleshed out to include literal source examples in a future stage. The goal here is to identify practical sources for these fields in the real world. ~1-3 sentences or unordered list.
-->
Expand Down Expand Up @@ -200,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

<!--
Who will be or has consulted on the contents of this RFC? Identify authorship and sponsorship, and optionally identify the nature of involvement of others. Link to GitHub aliases where possible. This list will likely change or grow stage after stage.
Expand All @@ -223,6 +200,7 @@ e.g.:
<!-- An RFC should link to the PRs for each of it stage advancements. -->

* Stage 0: https://github.com/elastic/ecs/pull/879
* Stage 2: https://github.com/elastic/ecs/pull/935

<!--
* Stage 1: https://github.com/elastic/ecs/pull/NNN
Expand Down
85 changes: 85 additions & 0 deletions rfcs/text/0004/session.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
- 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.

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".

"application" is relevant for application-level sessions such as web, ftp, database.

"system" is relevant for sessions initiated by computer systems rather than humans.

"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".

"local" is relevant e.g. for serial connections, physical sessions (hands on keyboard).

"remote" is relevant for any remote connection: direct system access via remote desktop, ssh, etc.

"virtual" is for VDI, VDA, etc.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we expand on "virtual" what are VDI and VDA?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

virtual desktop (rdp/citrix) and virtual desktop applications (citrix published apps - e.g. run just excel via citrix, no actual desktop just the app)


(missing clarifications for: wired, wireless and vpn network connections?)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Forgot to bring attention to this description.

When I reformatted it, I noticed we were missing definitions for wired, wireless and vpn. Could you add those please?


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. 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: 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: keyword
short: Session id or fingerprint.
description: >
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