[DOCS] [AWP] [8.2] Session View topic

docs/detections/detections-index.asciidoc

@@ -18,6 +18,8 @@ include::alerts-ui-manage.asciidoc[]
 
 include::visual-event-analyzer.asciidoc[]
 
+include::session-view.asciidoc[]
+
 include::query-alert-indices.asciidoc[]
 
 include::prebuilt-rules/tune-rule-signals.asciidoc[]

docs/detections/session-view.asciidoc

@@ -0,0 +1,85 @@
+[[session-view]]
+== Session View
+
+beta::[]
+
+Session View is an investigation tool that allows you to examine Linux process data organized
+in a tree-like structure according to the Linux logical event model, with processes organized by parentage and time of execution.
+It displays events in a highly readable format that is inspired by the terminal. This makes it a powerful tool for monitoring
+and investigating session activity on your Linux infrastructure and understanding user and service behavior.
+
+[float]
+[[session-view-data]]
+====== Session View displays:
+* *Interactive and non-interactive processes:* Processes and services with or without a controlling tty.
+* *User information:* The Linux user that executed each session or process, and any exec user changes.
+* *Process and event telemetry:* Process information included in the Linux logical event model.
+* *Nested sessions:* Sessions started by processes descended from the entry session.
+* *Alerts:* Alerts in the context of the processes which caused them.
+
+[float]
+[[enable-session-view]]
+=== Enable Session View data
+Session View uses process data collected by the {endpoint-sec} integration,
+but this data is not collected by default. To enable Session View data, go to *Manage* -> *Policies*
+and edit one or more of your {endpoint-sec} integration policies. On the *Policy settings* tab,
+scroll down to the Linux event collection section near the bottom of the page
+and switch on the *Include session data* toggle. Only data collected by {endpoint-sec} with this setting
+enabled can be viewed in Session View. For more information about the additional
+fields collected by {endpoint-sec} when this setting is enabled, refer to https://github.com/elastic/ecs/blob/main/rfcs/text/0030-linux-event-model.md[here].
+
+[float]
+[[open-session-view]]
+=== Open Session View
+Session View is accessible from the **Hosts**, **Alerts**, and **Timelines** pages.
+To open Session View, find an event or session you wish to view,
+then click *Open Session View* under *Actions*. For example:
+
+* On the Alerts page, go to *Detect* -> *Alerts*, then scroll down to view the Alerts table.
+Events viewable in Session View have a rectangular **Open Session View** icon under **Actions**:
+[role="screenshot"]
+image::images/session-view-action-icon-detail.png[Detail of the Open Session View icon,width=75%]
+
+* On the Hosts page, go to *Explore* -> *Hosts*, then select either the *Sessions* or the *Events* tab.
+From either of these tabs, click the *Open Session View* icon for an event or session.
+Labeled below are 1) the *Sessions* tab, and 2) the *Open Session View* icon:
+[role="screenshot"]
+image::images/session-view-hosts-page-sessions-tab-labeled.png[Detail of the Hosts page's Sessions tab]
+
+[discrete]
+[[session-view-ui]]
+=== Session View UI
+When you click *Open Session View*, the following display appears. Labeled features are described below:
+
+[role="screenshot"]
+image::images/session-view-terminal-labeled.png[Detail of Session view with labeled UI elements,width=150%]
+
+1. The *Close Session* and *Full screen* buttons.
+2. The search bar. Use it to find and highlight search terms within the current session.
+The buttons on the right side of the search bar allow you to jump through search results.
+3. The *display settings* button. Click to toggle Timestamps and Verbose mode.
+With Verbose mode enabled, Session View shows all processes created in a session, including shell startup,
+shell completion, and forks caused by built-in commands.
+It defaults to *off* in order to highlight the data most likely to be user-generated and non-standard.
+4. The *Detail panel* button. Click it to toggle the Detail panel, which appears below the button
+and displays a wide range of additional information about the selected process’s ancestry and host,
+and any associated alerts. To select a process in Session View, click on it.
+5. The startup process. In this example it shows that the session was a bash session.
+It also shows the Linux user "Ubuntu" started the session.
+6. The *Child processes* button. Click to expand or collapse a process’s children.
+You can also expand collapsed alerts and scripts where they appear.
+Collapsed processes will automatically expand when their contents match a search.
+7. The *Alerts* button. Click to show alerts caused by the parent process. Note the red line to the left
+of the process that caused the alert.
+
+Session View includes two additional icons not pictured above:
+
+* The *Script* button allows you to expand or collapse executed scripts:
+
+[role="screenshot"]
+image::images/session-view-script-button.png[The Script button]
+
+* The *Exec user change* badge highlights exec user changes, such as when a user escalates to root:
+
+[role="screenshot"]
+image::images/session-view-exec-user-change-badge.png[The Exec user change button]