Doc: Add docs for Auditbeat add_session_metadata processor (#40252) (#…

…40511)

Co-authored-by: Michael Wolf <[email protected]>
Co-authored-by: Nick Alayil <[email protected]>
Co-authored-by: DeDe Morton <[email protected]>
(cherry picked from commit 57ff337)

Co-authored-by: Karen Metts <[email protected]>

filebeat/docs/index.asciidoc

@@ -30,6 +30,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :linux_os:
 :docker_platform:
 :win_os:
+:no_add_session_metadata_processor:
 
 :kubernetes_default_indexers: {docdir}/kubernetes-default-indexers-matchers.asciidoc
 

heartbeat/docs/index.asciidoc

@@ -27,6 +27,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :no_decode_csv_fields_processor:
 :no_parse_aws_vpc_flow_log_processor:
 :no_timestamp_processor:
+:no_add_session_metadata_processor:
 
 include::{libbeat-dir}/shared-beats-attributes.asciidoc[]
 

libbeat/docs/processors-list.asciidoc

@@ -38,6 +38,9 @@ endif::[]
 ifndef::no_add_process_metadata_processor[]
 * <<add-process-metadata,`add_process_metadata`>>
 endif::[]
+ifndef::no_add_session_metadata_processor[]
+* <<add-session-metadata,`add_session_metadata`>>
+endif::[]
 ifndef::no_add_tags_processor[]
 * <<add-tags, `add_tags`>>
 endif::[]
@@ -180,6 +183,9 @@ endif::[]
 ifndef::no_add_process_metadata_processor[]
 include::{libbeat-processors-dir}/add_process_metadata/docs/add_process_metadata.asciidoc[]
 endif::[]
+ifndef::no_add_session_metadata_processor[]
+include::{x-auditbeat-processors-dir}/sessionmd/docs/add_session_metadata.asciidoc[]
+endif::[]
 ifndef::no_add_tags_processor[]
 include::{libbeat-processors-dir}/actions/docs/add_tags.asciidoc[]
 endif::[]

libbeat/docs/shared-beats-attributes.asciidoc

@@ -7,6 +7,7 @@
 :libbeat-processors-dir: {beats-root}/libbeat/processors
 :x-libbeat-processors-dir: {beats-root}/x-pack/libbeat/processors
 :libbeat-outputs-dir: {beats-root}/libbeat/outputs
+:x-auditbeat-processors-dir: {beats-root}/x-pack/auditbeat/processors
 :x-filebeat-processors-dir: {beats-root}/x-pack/filebeat/processors
 :winlogbeat-processors-dir: {beats-root}/winlogbeat/processors
 

metricbeat/docs/index.asciidoc

@@ -31,6 +31,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :no_decode_csv_fields_processor:
 :no_parse_aws_vpc_flow_log_processor:
 :no_timestamp_processor:
+:no_add_session_metadata_processor:
 
 :kubernetes_default_indexers: {docdir}/kubernetes-default-indexers-matchers.asciidoc
 

packetbeat/docs/index.asciidoc

@@ -28,6 +28,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :no_parse_aws_vpc_flow_log_processor:
 :no_script_processor:
 :no_timestamp_processor:
+:no_add_session_metadata_processor:
 
 include::{libbeat-dir}/shared-beats-attributes.asciidoc[]
 

winlogbeat/docs/index.asciidoc

@@ -24,6 +24,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :no_parse_aws_vpc_flow_log_processor:
 :include_translate_sid_processor:
 :export_pipeline:
+:no_add_session_metadata_processor:
 
 include::{libbeat-dir}/shared-beats-attributes.asciidoc[]
 

x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc

@@ -1,6 +1,99 @@
 [[add-session-metadata]]
-=== Add session metadata
+=== Add session metadata (Beta)
+++++
+<titleabbrev>add_session_metadata</titleabbrev>
+++++
 
-PLACEHOLDER
+beta::[]
 
+The `add_session_metadata` processor enriches process events with additional
+information that users can see using the {security-guide}/session-view.html[Session View] tool in the
+{elastic-sec} platform. 
 
+NOTE: The current release of `add_session_metadata` processor for {auditbeat} is limited to virtual machines (VMs) and bare metal environments.
+
+Here's an example using the `add_session_metadata` processor to enhance process events generated by
+the `auditd` module of {auditbeat}.
+
+[source,yaml]
+-------------------------------------
+auditbeat.modules:
+- module: auditd
+  processors:
+    - add_session_metadata:
+       backend: "auto"
+-------------------------------------
+
+[[add-session-metadata-explained]]
+==== How the `add_session_metadata` processor works
+
+Using the available Linux kernel technology, the processor collects comprehensive information on all running system processes, compiling this data into a process database. 
+When processing an event (such as those generated by the {auditbeat} `auditd` module), the processor queries this database to retrieve information about related processes, including the parent process, session leader, process group leader, and entry leader. 
+It then enriches the original event with this metadata, providing a more complete picture of process relationships and system activities. 
+
+This enhanced data enables the powerful {security-guide}/session-view.html[Session View] tool in the
+{elastic-sec} platform, offering users deeper insights for analysis and investigation.
+
+[[add-session-metadata-backends]]
+===== Backends
+
+The `add_session_metadata` processor operates using various backend options.
+
+* `auto` is the recommended setting.
+  It attempts to use `ebpf` first, falling back to `procfs` if necessary, ensuring compatibility even on systems without `ebpf` support.
+* `ebpf` collects process information with eBPF. 
+  This backend requires a system with Linux kernel 5.10.16 or above, kernel support for eBPF enabled, and auditbeat running as superuser.
+* `procfs` collects process information with the proc filesystem. 
+  This is compatible with older systems that may not support ebpf. 
+    To gather complete process info, auditbeat requires permissions to read all process data in procfs; for example, run as a superuser or have the `SYS_PTRACE` capability. 
+
+[[add-session-metadata-containers]]
+===== Containers
+If you are running {auditbeat} in a container, the container must run in the host's PID namespace. 
+With the `auto` or `ebpf` backend, these host directories must also be mounted to the same path within the container: `/sys/kernel/debug`, `/sys/fs/bpf`. 
+
+[[add-session-metadata-enable]]
+==== Enable and configure Session View in {auditbeat}
+
+To configure and enable {security-guide}/session-view.html[Session View] functionality, you'll:
+
+* Add the `add_sessions_metadata` processor to your `auditbeat.yml` file.
+* Configure audit rules in your `auditbeat.yml` file. 
+* Restart {auditbeat}.
+
+We'll walk you through these steps in more detail. 
+
+. Edit your `auditbeat.yml` file and add this info to the modules configuration section:
++
+[source,yaml]
+-------------------------------------
+auditbeat.modules:
+- module: auditd
+  processors:
+    - add_session_metadata:
+       backend: "auto"
+-------------------------------------
++
+. Add audit rules in the modules configuration section of `auditbeat.yml` or the
+`audit.rules.d` config file, depending on your configuration:
++
+[source,yaml]
+-------------------------------------
+auditbeat.modules:
+- module: auditd
+  audit_rules: |
+    ## executions
+    -a always,exit -F arch=b64 -S execve,execveat -k exec
+    -a always,exit -F arch=b64 -S exit_group
+    ## set_sid
+    -a always,exit -F arch=b64 -S setsid
+-------------------------------------
++
+. Save your configuration changes. 
++
+. Restart {auditbeat}: 
++
+[source,sh]
+-------------------------------------
+sudo systemctl restart auditbeat
+-------------------------------------

x-pack/functionbeat/docs/index.asciidoc

@@ -34,6 +34,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :no_script_processor:
 :no_timestamp_processor:
 :no_keystore:
+:no_add_session_metadata_processor:
 
 include::{libbeat-dir}/shared-beats-attributes.asciidoc[]