Doc: Add docs for Auditbeat add_session_metadata processor

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}/add_session_metadata/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
 

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

@@ -0,0 +1,90 @@
+[[add-session-metadata]]
+=== Add session metadata
+
+beta::[]
+
+++++
+<titleabbrev>add_session_metadata</titleabbrev>
+++++
+
+ifeval::["{beatname_lc}"=="auditbeat"]
+
+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. 
+
+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:
+       replace_fields: true
+       backend: "auto"
+-------------------------------------
+
+[[add-session-metadata-explained]]
+==== How the add_session_metadata processor works
+
+The `add_session_metadata` processor operates using various backend options, including `auto`, `ebpf`, and `procfs`. 
+The recommended `auto` setting attempts to use `ebpf` first, falling back to `procfs` if necessary, ensuring compatibility even on systems without `ebpf` support. 
+Future plans include adding `kprobe` support when the processor reaches GA status.
+
+//ToDo: Evaluate this statement. We're careful about what we promise in official documentation. 
+
+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-enable]]
+==== Enable and configure Session View in {auditbeat}
+
+To configure and enable 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:
+       replace_fields: true
+       backend: "auto"
+-------------------------------------
+
+. Add audit rules in the modules configuration section of `auditbeat.yml`:
+
+[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
+-------------------------------------
+
+endif::[]