From e2e9ea17f94e2263d04bb9c27621680361de79b5 Mon Sep 17 00:00:00 2001 From: t0x01 Date: Thu, 19 Sep 2024 15:27:22 +0400 Subject: [PATCH] docs: Add ancestors and ancestor filter information Add information about ancestors, ancestor filter and ancestors related metrics to documentation. Signed-off-by: t0x01 --- api/v1/README.md | 6 ++++++ docs/content/en/docs/concepts/events.md | 1 + docs/content/en/docs/reference/grpc-api.md | 6 ++++++ docs/content/en/docs/reference/metrics.md | 4 ++-- docs/data/tetragon_flags.yaml | 5 +++-- examples/configuration/tetragon.yaml | 2 +- 6 files changed, 19 insertions(+), 5 deletions(-) diff --git a/api/v1/README.md b/api/v1/README.md index 85eedda1ca9..3f605848ee4 100644 --- a/api/v1/README.md +++ b/api/v1/README.md @@ -889,6 +889,7 @@ found. | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | Process that triggered the exit. | | parent | [Process](#tetragon-Process) | | Immediate parent of the process. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | signal | [string](#string) | | Signal that the process received when it exited, for example SIGKILL or SIGTERM (list all signal names with `kill -l`). If there is no signal handler implemented for a specific process, we report the exit status code that can be found in the status field. | | status | [uint32](#uint32) | | Status code on process exit. For example, the status code can indicate if an error was encountered or the program exited successfully. | | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Date and time of the event. | @@ -908,6 +909,7 @@ found. | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | Process that triggered the kprobe. | | parent | [Process](#tetragon-Process) | | Immediate parent of the process. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | function_name | [string](#string) | | Symbol on which the kprobe was attached. | | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed kprobe. | | return | [KprobeArgument](#tetragon-KprobeArgument) | | Return value definition of the observed kprobe. | @@ -951,6 +953,7 @@ loader sensor event triggered for loaded binary/library | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | | | parent | [Process](#tetragon-Process) | | | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | function_name | [string](#string) | | LSM hook name. | | policy_name | [string](#string) | | Name of the policy that created that LSM hook. | | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | @@ -973,6 +976,7 @@ loader sensor event triggered for loaded binary/library | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | Process that triggered the tracepoint. | | parent | [Process](#tetragon-Process) | | Immediate parent of the process. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | subsys | [string](#string) | | Subsystem of the tracepoint. | | event | [string](#string) | | Event of the subsystem. | | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed tracepoint. TODO: once we implement all we want, rename KprobeArgument to GenericArgument | @@ -996,6 +1000,7 @@ loader sensor event triggered for loaded binary/library | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | | | parent | [Process](#tetragon-Process) | | | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | path | [string](#string) | | | | symbol | [string](#string) | | | | policy_name | [string](#string) | | Name of the policy that created that uprobe. | @@ -1294,6 +1299,7 @@ Capability set to filter over. NOTE: you may specify only ONE set here. | policy_names | [string](#string) | repeated | Filter events by tracing policy names | | capabilities | [CapFilter](#tetragon-CapFilter) | | Filter events by Linux process capability | | parent_binary_regex | [string](#string) | repeated | Filter parent process' binary using RE2 regular expression syntax. | +| ancestor_binary_regex | [string](#string) | repeated | Filter ancestor processes' binary using RE2 regular expression syntax. | diff --git a/docs/content/en/docs/concepts/events.md b/docs/content/en/docs/concepts/events.md index fe585ee5cfa..6730076ea6b 100644 --- a/docs/content/en/docs/concepts/events.md +++ b/docs/content/en/docs/concepts/events.md @@ -162,6 +162,7 @@ flags, or environment variables. | `policy_names` | Filter events by tracing policy names. | | `capabilities` | Filter events by Linux process capability. | | `parent_binary_regex` | Filter process events by a list of regular expressions of parent process binary names (e.g. `"^/home/kubernetes/bin/kubelet$"`). You can find the full syntax [here](https://github.com/google/re2/wiki/Syntax). | +| `ancestor_binary_regex` | Filter process events by a list of regular expressions of ancestor processes' binary names (e.g. `"^/home/kubernetes/bin/kubelet$"`). You can find the full syntax [here](https://github.com/google/re2/wiki/Syntax). | #### Field Filtering diff --git a/docs/content/en/docs/reference/grpc-api.md b/docs/content/en/docs/reference/grpc-api.md index 439a0e90fbf..6f5e7aaec7f 100644 --- a/docs/content/en/docs/reference/grpc-api.md +++ b/docs/content/en/docs/reference/grpc-api.md @@ -521,6 +521,7 @@ found. | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | Process that triggered the exit. | | parent | [Process](#tetragon-Process) | | Immediate parent of the process. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | signal | [string](#string) | | Signal that the process received when it exited, for example SIGKILL or SIGTERM (list all signal names with `kill -l`). If there is no signal handler implemented for a specific process, we report the exit status code that can be found in the status field. | | status | [uint32](#uint32) | | Status code on process exit. For example, the status code can indicate if an error was encountered or the program exited successfully. | | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Date and time of the event. | @@ -533,6 +534,7 @@ found. | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | Process that triggered the kprobe. | | parent | [Process](#tetragon-Process) | | Immediate parent of the process. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | function_name | [string](#string) | | Symbol on which the kprobe was attached. | | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed kprobe. | | return | [KprobeArgument](#tetragon-KprobeArgument) | | Return value definition of the observed kprobe. | @@ -563,6 +565,7 @@ loader sensor event triggered for loaded binary/library | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | | | parent | [Process](#tetragon-Process) | | | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | function_name | [string](#string) | | LSM hook name. | | policy_name | [string](#string) | | Name of the policy that created that LSM hook. | | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | @@ -578,6 +581,7 @@ loader sensor event triggered for loaded binary/library | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | Process that triggered the tracepoint. | | parent | [Process](#tetragon-Process) | | Immediate parent of the process. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | subsys | [string](#string) | | Subsystem of the tracepoint. | | event | [string](#string) | | Event of the subsystem. | | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed tracepoint. TODO: once we implement all we want, rename KprobeArgument to GenericArgument | @@ -594,6 +598,7 @@ loader sensor event triggered for loaded binary/library | ----- | ---- | ----- | ----------- | | process | [Process](#tetragon-Process) | | | | parent | [Process](#tetragon-Process) | | | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | path | [string](#string) | | | | symbol | [string](#string) | | | | policy_name | [string](#string) | | Name of the policy that created that uprobe. | @@ -792,6 +797,7 @@ Capability set to filter over. NOTE: you may specify only ONE set here. | policy_names | [string](#string) | repeated | Filter events by tracing policy names | | capabilities | [CapFilter](#tetragon-CapFilter) | | Filter events by Linux process capability | | parent_binary_regex | [string](#string) | repeated | Filter parent process' binary using RE2 regular expression syntax. | +| ancestor_binary_regex | [string](#string) | repeated | Filter ancestor processes' binaries using RE2 regular expression syntax. | diff --git a/docs/content/en/docs/reference/metrics.md b/docs/content/en/docs/reference/metrics.md index 067247b0ec5..46a05010129 100644 --- a/docs/content/en/docs/reference/metrics.md +++ b/docs/content/en/docs/reference/metrics.md @@ -72,7 +72,7 @@ Number of failed fetches from the event cache. These won't be retried as they al | label | values | | ----- | ------ | -| `entry_type` | `parent_info, pod_info, process_info` | +| `entry_type` | `ancestors_info`, `parent_info, pod_info, process_info` | | `event_type` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_LSM, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO` | ### `tetragon_event_cache_fetch_retries_total` @@ -81,7 +81,7 @@ Number of retries when fetching info from the event cache. | label | values | | ----- | ------ | -| `entry_type` | `parent_info, pod_info, process_info` | +| `entry_type` | `ancestors_info`, `parent_info, pod_info, process_info` | ### `tetragon_event_cache_inserts_total` diff --git a/docs/data/tetragon_flags.yaml b/docs/data/tetragon_flags.yaml index a023cbc756f..049f005b688 100644 --- a/docs/data/tetragon_flags.yaml +++ b/docs/data/tetragon_flags.yaml @@ -63,8 +63,9 @@ options: default_value: "false" usage: Enable policy filter debug messages - name: enable-process-ancestors - default_value: "true" - usage: Include ancestors in process exec events + default_value: "false" + usage: | + Include ancestors in process_exec, process_exit, process_uprobe, process_kprobe, process_lsm, process_tracepoint events - name: enable-process-cred default_value: "false" usage: Enable process_cred events diff --git a/examples/configuration/tetragon.yaml b/examples/configuration/tetragon.yaml index c176ae219bd..7c96d659d0a 100644 --- a/examples/configuration/tetragon.yaml +++ b/examples/configuration/tetragon.yaml @@ -16,7 +16,7 @@ debug: false disable-kprobe-multi: false enable-export-aggregation: false enable-k8s-api: false -enable-process-ancestors: true +enable-process-ancestors: false enable-process-cred: false enable-process-ns: false event-queue-size: 10000