From a0741167ac976055ceb6082add3ace501e74ddcc Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Mon, 15 Jul 2024 16:47:00 -0400 Subject: [PATCH 01/12] Doc: Add docs for add_session_metadata processor --- libbeat/docs/processors-list.asciidoc | 6 ++ libbeat/docs/shared-beats-attributes.asciidoc | 1 + .../docs/add_session_metadata.asciidoc | 90 +++++++++++++++++++ 3 files changed, 97 insertions(+) create mode 100644 x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc diff --git a/libbeat/docs/processors-list.asciidoc b/libbeat/docs/processors-list.asciidoc index b95f163cefcf..8a253c34cdf7 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}/add_session_metadata/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 c2e83951bc55..7b04a7e87cca 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/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc new file mode 100644 index 000000000000..369089804f89 --- /dev/null +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -0,0 +1,90 @@ +[[add-session-metadata]] +=== Add session metadata + +beta::[] + +++++ +add_session_metadata +++++ + +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::[] From b2831701a043601f970a9c098b5ea249d57d6274 Mon Sep 17 00:00:00 2001 From: Karen Metts <35154725+karenzone@users.noreply.github.com> Date: Wed, 24 Jul 2024 13:35:36 -0400 Subject: [PATCH 02/12] Apply suggestions from code review Co-authored-by: Michael Wolf --- .../processors/sessionmd/docs/add_session_metadata.asciidoc | 5 ----- 1 file changed, 5 deletions(-) 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 369089804f89..912c3f46332b 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -22,7 +22,6 @@ auditbeat.modules: - module: auditd processors: - add_session_metadata: - replace_fields: true backend: "auto" ------------------------------------- @@ -31,9 +30,6 @@ auditbeat.modules: 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. @@ -60,7 +56,6 @@ auditbeat.modules: - module: auditd processors: - add_session_metadata: - replace_fields: true backend: "auto" ------------------------------------- From d43d705983fad7e045f789c37cd577ddaa9b6f33 Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Wed, 24 Jul 2024 14:41:46 -0400 Subject: [PATCH 03/12] Mention config file option --- .../processors/sessionmd/docs/add_session_metadata.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 912c3f46332b..211353149824 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -59,7 +59,8 @@ auditbeat.modules: backend: "auto" ------------------------------------- -. Add audit rules in the modules configuration section of `auditbeat.yml`: +. Add audit rules in the modules configuration section of `auditbeat.yml` or the +`audit.rules.d` config file, depending on your configuration: [source,yaml] ------------------------------------- From e92f42ac287b2b71551436f03c9175f43c833583 Mon Sep 17 00:00:00 2001 From: Karen Metts <35154725+karenzone@users.noreply.github.com> Date: Wed, 24 Jul 2024 20:03:11 -0400 Subject: [PATCH 04/12] Content tweak --- .../processors/sessionmd/docs/add_session_metadata.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 211353149824..5e9eb9d0824f 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -59,7 +59,7 @@ auditbeat.modules: backend: "auto" ------------------------------------- -. Add audit rules in the modules configuration section of `auditbeat.yml` or the +. Add audit rules in the modules configuration section of `auditbeat.yml` or an `audit.rules.d` config file, depending on your configuration: [source,yaml] From 34a4ec8ac3fad1e9dbcd4d5b63c23a9add74a3fa Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Wed, 24 Jul 2024 15:07:01 -0400 Subject: [PATCH 05/12] Tweak --- .../docs/add_session_metadata.asciidoc | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) 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 adb075e80601..ccba1196aa1f 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -1,5 +1,5 @@ [[add-session-metadata]] -=== Add session metadata +=== Add session metadata (Beta) beta::[] @@ -26,7 +26,7 @@ auditbeat.modules: ------------------------------------- [[add-session-metadata-explained]] -==== How the add_session_metadata processor works +==== 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. @@ -34,6 +34,7 @@ The recommended `auto` setting attempts to use `ebpf` first, falling back to `pr 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. @@ -49,7 +50,7 @@ To configure and enable Session View functionality, you'll: 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: @@ -58,10 +59,10 @@ auditbeat.modules: - add_session_metadata: backend: "auto" ------------------------------------- - -. Add audit rules in the modules configuration section of `auditbeat.yml` or an ++ +. 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: @@ -73,11 +74,11 @@ auditbeat.modules: ## set_sid -a always,exit -F arch=b64 -S setsid ------------------------------------- - ++ . Save your configuration changes. - ++ . Restart {auditbeat}: - ++ [source,sh] ------------------------------------- sudo systemctl restart auditbeat From ed5ba57c582f730322b1a92549d1de1cf480e8ad Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Tue, 30 Jul 2024 18:52:58 -0400 Subject: [PATCH 06/12] Fix directory path to get docs building and add review comments --- libbeat/docs/processors-list.asciidoc | 2 +- .../processors/sessionmd/docs/add_session_metadata.asciidoc | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/libbeat/docs/processors-list.asciidoc b/libbeat/docs/processors-list.asciidoc index 8a253c34cdf7..4105666049d6 100644 --- a/libbeat/docs/processors-list.asciidoc +++ b/libbeat/docs/processors-list.asciidoc @@ -184,7 +184,7 @@ 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[] +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[] 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 ccba1196aa1f..081cf7403983 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -13,6 +13,8 @@ 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}. From 8d1dda2d34c14779baaa6a0667aeb54cfb71ae52 Mon Sep 17 00:00:00 2001 From: Karen Metts <35154725+karenzone@users.noreply.github.com> Date: Mon, 5 Aug 2024 17:47:26 -0400 Subject: [PATCH 07/12] Apply suggestions from code review Co-authored-by: DeDe Morton --- .../sessionmd/docs/add_session_metadata.asciidoc | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) 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 081cf7403983..bb8d9fde6fda 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -7,7 +7,6 @@ beta::[] add_session_metadata ++++ -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 @@ -45,7 +44,7 @@ This enhanced data enables the powerful {security-guide}/session-view.html[Sessi To configure and enable Session View functionality, you'll: -* Add the `add_sessions-metadata` processor to your `auditbeat.yml` file. +* Add the `add_sessions_metadata` processor to your `auditbeat.yml` file. * Configure audit rules in your `auditbeat.yml` file. * Restart {auditbeat}. @@ -84,6 +83,4 @@ auditbeat.modules: [source,sh] ------------------------------------- sudo systemctl restart auditbeat -------------------------------------- - -endif::[] \ No newline at end of file +------------------------------------- \ No newline at end of file From 794e8acff5d9970f19e1ded2c6b93b5a32d82b46 Mon Sep 17 00:00:00 2001 From: dedemorton Date: Mon, 5 Aug 2024 14:53:16 -0700 Subject: [PATCH 08/12] Fix Filebeat build error --- filebeat/docs/index.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc index 4399fc17e286..aedc0f74de6d 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 From c843a64198b3a728541d02e95be184f2adc5ec5d Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Mon, 5 Aug 2024 18:57:02 -0400 Subject: [PATCH 09/12] Propagate exclusion attribute to other beats --- heartbeat/docs/index.asciidoc | 1 + metricbeat/docs/index.asciidoc | 1 + packetbeat/docs/index.asciidoc | 1 + winlogbeat/docs/index.asciidoc | 1 + 4 files changed, 4 insertions(+) diff --git a/heartbeat/docs/index.asciidoc b/heartbeat/docs/index.asciidoc index 1912e1efb1ac..e2d56f8ef5a9 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/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc index 94c888e6b794..d5b137af48fd 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 a63b828dc1df..d0590b5d872d 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 2d41512a9bc5..6b3e77eaf9a8 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[] From 097018150ea93fb16210dca98a3eca54f02d800d Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Mon, 5 Aug 2024 19:18:15 -0400 Subject: [PATCH 10/12] Set exclusion attribute for functionbeat --- x-pack/functionbeat/docs/index.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/x-pack/functionbeat/docs/index.asciidoc b/x-pack/functionbeat/docs/index.asciidoc index a54cc91c4f43..3ab8578a0bc2 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[] From ab87cb63307b0826128acdd6f46657db8537d4c5 Mon Sep 17 00:00:00 2001 From: Karen Metts <35154725+karenzone@users.noreply.github.com> Date: Thu, 8 Aug 2024 16:28:06 -0400 Subject: [PATCH 11/12] Add backend and container info Co-authored-by: Michael Wolf --- .../sessionmd/docs/add_session_metadata.asciidoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) 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 bb8d9fde6fda..fdf9737a1b21 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -29,7 +29,13 @@ auditbeat.modules: [[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`. +==== Backends +* `auto` is the recommended setting, and will attempt to use `ebpf` first, falling back to `procfs` if necessary, ensuring compatibility even on systems without `ebpf` support. +* `ebpf` will collect 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` will collect 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. + +==== Containers +If 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` The recommended `auto` setting attempts to use `ebpf` first, falling back to `procfs` if necessary, ensuring compatibility even on systems without `ebpf` support. Using the available Linux kernel technology, the processor collects comprehensive information on all running system processes, compiling this data into a process database. From 8f1c2e041b5aff370f20283822e0edbeb93cd330 Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Thu, 8 Aug 2024 17:24:39 -0400 Subject: [PATCH 12/12] Edit and refine content pre-publish --- .../docs/add_session_metadata.asciidoc | 33 +++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) 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 fdf9737a1b21..d29c5d0ac80b 100644 --- a/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc +++ b/x-pack/auditbeat/processors/sessionmd/docs/add_session_metadata.asciidoc @@ -1,12 +1,10 @@ [[add-session-metadata]] === Add session metadata (Beta) - -beta::[] - ++++ add_session_metadata ++++ +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 @@ -29,15 +27,6 @@ auditbeat.modules: [[add-session-metadata-explained]] ==== How the `add_session_metadata` processor works -==== Backends -* `auto` is the recommended setting, and will attempt to use `ebpf` first, falling back to `procfs` if necessary, ensuring compatibility even on systems without `ebpf` support. -* `ebpf` will collect 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` will collect 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. - -==== Containers -If 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` -The recommended `auto` setting attempts to use `ebpf` first, falling back to `procfs` if necessary, ensuring compatibility even on systems without `ebpf` support. - 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. @@ -45,10 +34,28 @@ It then enriches the original event with this metadata, providing a more complet 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 Session View functionality, you'll: +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.