diff --git a/docs/detections/detections-index.asciidoc b/docs/detections/detections-index.asciidoc index 61fa9ce2ba..83ad95209f 100644 --- a/docs/detections/detections-index.asciidoc +++ b/docs/detections/detections-index.asciidoc @@ -22,6 +22,8 @@ include::alerts-run-osquery.asciidoc[] include::visual-event-analyzer.asciidoc[] +include::session-view.asciidoc[] + include::query-alert-indices.asciidoc[] include::prebuilt-rules/tune-rule-signals.asciidoc[] diff --git a/docs/detections/images/session-view-action-icon-detail.png b/docs/detections/images/session-view-action-icon-detail.png new file mode 100644 index 0000000000..4646f7e454 Binary files /dev/null and b/docs/detections/images/session-view-action-icon-detail.png differ diff --git a/docs/detections/images/session-view-exec-user-change-badge.png b/docs/detections/images/session-view-exec-user-change-badge.png new file mode 100644 index 0000000000..f95707bd1e Binary files /dev/null and b/docs/detections/images/session-view-exec-user-change-badge.png differ diff --git a/docs/detections/images/session-view-hosts-page-sessions-tab-labeled.png b/docs/detections/images/session-view-hosts-page-sessions-tab-labeled.png new file mode 100644 index 0000000000..42c7071b88 Binary files /dev/null and b/docs/detections/images/session-view-hosts-page-sessions-tab-labeled.png differ diff --git a/docs/detections/images/session-view-script-button.png b/docs/detections/images/session-view-script-button.png new file mode 100644 index 0000000000..9ddea9446e Binary files /dev/null and b/docs/detections/images/session-view-script-button.png differ diff --git a/docs/detections/images/session-view-terminal-labeled.png b/docs/detections/images/session-view-terminal-labeled.png new file mode 100644 index 0000000000..13c73238c7 Binary files /dev/null and b/docs/detections/images/session-view-terminal-labeled.png differ diff --git a/docs/detections/session-view.asciidoc b/docs/detections/session-view.asciidoc new file mode 100644 index 0000000000..4aff48014a --- /dev/null +++ b/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 the *Include session data* toggle on. Session View can only display data that was +collected by {endpoint-sec} when this setting was enabled. For more information about the additional +fields collected by {endpoint-sec} when this setting is enabled, refer to the https://github.com/elastic/ecs/blob/main/rfcs/text/0030-linux-event-model.md[Linux event model RFC] + +[float] +[[open-session-view]] +=== Open Session View +Session View is accessible from the **Hosts**, **Alerts**, and **Timelines** pages. +Events and sessions that you can investigate in Session View have a rectangular +*Open Session View* button in the *Actions* column. For example: + +* On the Alerts page (*Detect* -> *Alerts*), scroll down to view the Alerts table. +Look for alerts that have the **Open Session View** button in the **Actions** column: +[role="screenshot"] +image::images/session-view-action-icon-detail.png[Detail of the Open Session View icon,width=75%] + +* On the Hosts page (*Explore* -> *Hosts*), select 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 +The Session View UI has the following features: + +[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* 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]