[Docs] Update documentation for powering up Session View with Auditbeat/Auditd Manager events

[nick-alayil]

Background

The documentation needs to update to reflect the recent enhancements made to power up the Session View using Auditbeat events. These improvements apply to both Auditbeat Events (beat) and Auditd Manager (agent & fleet managed) integrations.

All features and enhancements described below are in beta state for the 8.15 release. This must be clearly communicated to the readers throughout the documentation.

Documentation Content

New Processor: add_session_metadata

The following documentation page needs to be updated to include information about the new add_session_metadata processor.
https://www.elastic.co/guide/en/beats/auditbeat/current/filtering-and-enhancing-data.html

The add_session_metadata processor enriches process events with additional information/metadata necessary to enable the session viewer capability in the Elastic Security platform. Below is an example of using this processor to enhance process events generated by the auditd module of Auditbeat:

auditbeat.modules:
- module: auditd
  processors:
    - add_session_metadata:
       replace_fields: true
       backend: "auto"

How the add_session_metadata Processor Works?

The add_session_metadata processor operates by leveraging 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. 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 Auditbeat's 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 additional metadata, providing a more complete picture of process relationships and system activities. This enhanced data enables the powerful session view functionality in the Elastic Security platform, offering users deeper insights for analysis and investigation.

Enabling Session Viewer

To enable the Session Viewer functionality for Auditbeat and Auditd Manager integrations, documentation updates are required in the following pages:

https://www.elastic.co/guide/en/beats/auditbeat/current/configuring-howto-auditbeat.html
https://www.elastic.co/docs/current/integrations/auditd_manager

These pages should be updated to include information on how to configure and enable the add_session_metadata processor for enhancing process events.

To visualize Linux process events instrumented via the auditd module in Session Viewer, follow these configuration steps for Auditbeat and Auditd Manager integrations:

For Auditbeat:

1. Add the add_session_metadata processor: Edit your auditbeat.yml file and add the following under the modules configuration section:

auditbeat.modules:
- module: auditd
  processors:
    - add_session_metadata:
       replace_fields: true
       backend: "auto"

2. Configure audit rules: In the same auditbeat.yml file, add the following audit rules under the modules configuration section:

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

3. Restart Auditbeat: After saving the configuration changes, restart the Auditbeat

sudo systemctl restart auditbeat

For Auditd Manager Integration:

The configuration changes are similar to Auditbeat, but they are applied through the Kibana Auditd Manager integration configuration page:

1. Navigate to the Auditd Manager integration configuration in Kibana.
2. Add the add_session_metadata processor configuration under the advanced options section.
   
3. Configure the audit rules.
   

Note: For Auditd Manager integration, there's no need to manually restart the service as changes are automatically applied.

[nick-alayil]

Cc @benironside @karenzone

[karenzone]

Related issue

• [Integration]: [Docs] Update documentation for powering up Session View with Auditbeat/Auditd Manager events #40186

Primary PRs

• [Auditbeat]: Doc: Add docs for Auditbeat add_session_metadata processor #40252
• [Integration]: [Auditd Manager] Add docs to support add_session_metadata processor integrations#10544

Supporting PRs to get new docs added to buildstream

• [Docs]: Add x-pack-auditbeat to conf.yaml docs#3038
• [Beats] Auditbeat: Add placeholder for new docs directory and file #40357
• [Beats] [8.15](backport #40357) Auditbeat: Add placeholder for new docs directory and file #40370

[karenzone]

Update

Complete

• Auditbeat: Doc: Add docs for Auditbeat add_session_metadata processor #40252 🎉
• Auditd Manager integration: [Auditd Manager] Add docs to support add_session_metadata processor integrations#10544 🎉