From 9721f204277f7e3a7a84a66d97cd0e32a9d441ef Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 13 Aug 2024 17:48:56 -0400 Subject: [PATCH] Doc: Add docs for Auditbeat add_session_metadata processor (#40252) (#40511) Co-authored-by: Michael Wolf Co-authored-by: Nick Alayil Co-authored-by: DeDe Morton (cherry picked from commit 57ff3378dff655c490332aa306b5b6c2af2ef94f) Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com> --- filebeat/docs/index.asciidoc | 1 + heartbeat/docs/index.asciidoc | 1 + libbeat/docs/processors-list.asciidoc | 6 ++ libbeat/docs/shared-beats-attributes.asciidoc | 1 + metricbeat/docs/index.asciidoc | 1 + packetbeat/docs/index.asciidoc | 1 + winlogbeat/docs/index.asciidoc | 1 + .../docs/add_session_metadata.asciidoc | 97 ++++++++++++++++++- x-pack/functionbeat/docs/index.asciidoc | 1 + 9 files changed, 108 insertions(+), 2 deletions(-) diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc index 4399fc17e28..aedc0f74de6 100644 --- a/filebeat/docs/index.asciidoc +++ b/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 diff --git a/heartbeat/docs/index.asciidoc b/heartbeat/docs/index.asciidoc index 1912e1efb1a..e2d56f8ef5a 100644 --- a/heartbeat/docs/index.asciidoc +++ b/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[] diff --git a/libbeat/docs/processors-list.asciidoc b/libbeat/docs/processors-list.asciidoc index b95f163cefc..4105666049d 100644 --- a/libbeat/docs/processors-list.asciidoc +++ b/libbeat/docs/processors-list.asciidoc @@ -38,6 +38,9 @@ endif::[] ifndef::no_add_process_metadata_processor[] * <> endif::[] +ifndef::no_add_session_metadata_processor[] +* <> +endif::[] ifndef::no_add_tags_processor[] * <> 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::[] diff --git a/libbeat/docs/shared-beats-attributes.asciidoc b/libbeat/docs/shared-beats-attributes.asciidoc index c2e83951bc5..7b04a7e87cc 100644 --- a/libbeat/docs/shared-beats-attributes.asciidoc +++ b/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 diff --git a/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc index 94c888e6b79..d5b137af48f 100644 --- a/metricbeat/docs/index.asciidoc +++ b/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 diff --git a/packetbeat/docs/index.asciidoc b/packetbeat/docs/index.asciidoc index a63b828dc1d..d0590b5d872 100644 --- a/packetbeat/docs/index.asciidoc +++ b/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[] diff --git a/winlogbeat/docs/index.asciidoc b/winlogbeat/docs/index.asciidoc index 2d41512a9bc..6b3e77eaf9a 100644 --- a/winlogbeat/docs/index.asciidoc +++ b/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[] diff --git a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc index 7a5d9c90ac4..d29c5d0ac80 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -1,6 +1,99 @@ [[add-session-metadata]] -=== Add session metadata +=== Add session metadata (Beta) +++++ +add_session_metadata +++++ -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 +------------------------------------- \ No newline at end of file diff --git a/x-pack/functionbeat/docs/index.asciidoc b/x-pack/functionbeat/docs/index.asciidoc index a54cc91c4f4..3ab8578a0bc 100644 --- a/x-pack/functionbeat/docs/index.asciidoc +++ b/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[]