From 558ee86357d0628bf90301ed722420ab2ae96f4f 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 fa8ffb21e26..76e7fd40f65 100644 --- a/api/v1/README.md +++ b/api/v1/README.md @@ -956,6 +956,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. | @@ -975,6 +976,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. | @@ -1018,6 +1020,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. | @@ -1041,6 +1044,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 | @@ -1064,6 +1068,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. | @@ -1362,6 +1367,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 3dc6d8bbdef..bc3f08e6ade 100644 --- a/docs/content/en/docs/reference/grpc-api.md +++ b/docs/content/en/docs/reference/grpc-api.md @@ -570,6 +570,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. | @@ -582,6 +583,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. | @@ -612,6 +614,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. | @@ -628,6 +631,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 | @@ -644,6 +648,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. | @@ -842,6 +847,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 bec127bc64b..7e49447fddb 100644 --- a/docs/content/en/docs/reference/metrics.md +++ b/docs/content/en/docs/reference/metrics.md @@ -92,7 +92,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` @@ -101,7 +101,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