diff --git a/api/v1/README.md b/api/v1/README.md index d357a634950..39b2313d3ad 100644 --- a/api/v1/README.md +++ b/api/v1/README.md @@ -1006,6 +1006,7 @@ found. | 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. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -1032,6 +1033,7 @@ found. | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | | user_stack_trace | [StackTraceEntry](#tetragon-StackTraceEntry) | repeated | User-mode stack trace to the call. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -1071,6 +1073,7 @@ loader sensor event triggered for loaded binary/library | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed LSM hook. | | action | [KprobeAction](#tetragon-KprobeAction) | | Action performed when the LSM hook matched. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | ima_hash | [string](#string) | | IMA file hash. Format algorithm:value. | @@ -1095,6 +1098,7 @@ loader sensor event triggered for loaded binary/library | action | [KprobeAction](#tetragon-KprobeAction) | | Action performed when the tracepoint matched. | | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -1117,6 +1121,7 @@ loader sensor event triggered for loaded binary/library | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed uprobe. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -1430,6 +1435,7 @@ Capability set to filter over. NOTE: you may specify only ONE set here. | parent_arguments_regex | [string](#string) | repeated | Filter by process.parent.arguments field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | container_id | [string](#string) | repeated | Filter by the container ID in the process.docker field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | in_init_tree | [google.protobuf.BoolValue](#google-protobuf-BoolValue) | | Filter containerized processes based on whether they are descendants of the container's init process. This can be used, for example, to watch for processes injected into a container via docker exec, kubectl exec, or similar mechanisms. | +| ancestor_binary_regex | [string](#string) | repeated | Filter ancestor processes' binaries using RE2 regular expression syntax. | @@ -2009,7 +2015,7 @@ Determines the behavior of a field filter | process | [Process](#tetragon-Process) | | | | color | [string](#string) | | | | refcnt | [google.protobuf.UInt32Value](#google-protobuf-UInt32Value) | | | -| refcnt_ops | [ProcessInternal.RefcntOpsEntry](#tetragon-ProcessInternal-RefcntOpsEntry) | repeated | refcnt_ops is a map of operations to refcnt change keys can be: - "process++": process increased refcnt (i.e. this process starts) - "process--": process decreased refcnt (i.e. this process exits) - "parent++": parent increased refcnt (i.e. a process starts that has this process as a parent) - "parent--": parent decreased refcnt (i.e. a process exits that has this process as a parent) | +| refcnt_ops | [ProcessInternal.RefcntOpsEntry](#tetragon-ProcessInternal-RefcntOpsEntry) | repeated | refcnt_ops is a map of operations to refcnt change keys can be: - "process++": process increased refcnt (i.e. this process starts) - "process--": process decreased refcnt (i.e. this process exits) - "parent++": parent increased refcnt (i.e. a process starts that has this process as a parent) - "parent--": parent decreased refcnt (i.e. a process exits that has this process as a parent) - "ancestor++": ancestor increased refcnt (i.e. a process starts that has this process as an ancestor) - "ancestor--": ancestor decreased refcnt (i.e. a process exits that has this process as an ancestor) | diff --git a/docs/content/en/docs/concepts/events.md b/docs/content/en/docs/concepts/events.md index 5e53958d9bc..f4292e7c281 100644 --- a/docs/content/en/docs/concepts/events.md +++ b/docs/content/en/docs/concepts/events.md @@ -166,8 +166,9 @@ flags, or environment variables. | `parent_arguments_regex` | Filter by the container ID in the process.docker field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | `container_id` | Filter by parent process arguments using a list of regular expressions. You can find the full syntax [here](https://github.com/google/re2/wiki/Syntax). | | `in_init_tree` | Filter containerized processes based on whether they are descendants of the container's init process. This can be used, for example, to watch for processes injected into a container via docker exec, kubectl exec, or similar mechanisms. | +| `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 +#### Field Filtering In some cases, it is not desirable to include all of the fields exported in Tetragon events by default. In these cases, you can use field filters to diff --git a/docs/content/en/docs/reference/grpc-api.md b/docs/content/en/docs/reference/grpc-api.md index 2575a5aa6a0..718a1c2154d 100644 --- a/docs/content/en/docs/reference/grpc-api.md +++ b/docs/content/en/docs/reference/grpc-api.md @@ -615,6 +615,7 @@ found. | 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. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -634,6 +635,7 @@ found. | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | | user_stack_trace | [StackTraceEntry](#tetragon-StackTraceEntry) | repeated | User-mode stack trace to the call. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -660,6 +662,7 @@ loader sensor event triggered for loaded binary/library | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed LSM hook. | | action | [KprobeAction](#tetragon-KprobeAction) | | Action performed when the LSM hook matched. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | | ima_hash | [string](#string) | | IMA file hash. Format algorithm:value. | @@ -677,6 +680,7 @@ loader sensor event triggered for loaded binary/library | action | [KprobeAction](#tetragon-KprobeAction) | | Action performed when the tracepoint matched. | | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -692,6 +696,7 @@ loader sensor event triggered for loaded binary/library | message | [string](#string) | | Short message of the Tracing Policy to inform users what is going on. | | args | [KprobeArgument](#tetragon-KprobeArgument) | repeated | Arguments definition of the observed uprobe. | | tags | [string](#string) | repeated | Tags of the Tracing Policy to categorize the event. | +| ancestors | [Process](#tetragon-Process) | repeated | Ancestors of the process beyond the immediate parent. | @@ -898,6 +903,7 @@ Capability set to filter over. NOTE: you may specify only ONE set here. | parent_arguments_regex | [string](#string) | repeated | Filter by process.parent.arguments field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | container_id | [string](#string) | repeated | Filter by the container ID in the process.docker field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | in_init_tree | [google.protobuf.BoolValue](#google-protobuf-BoolValue) | | Filter containerized processes based on whether they are descendants of the container's init process. This can be used, for example, to watch for processes injected into a container via docker exec, kubectl exec, or similar mechanisms. | +| ancestor_binary_regex | [string](#string) | repeated | Filter ancestor processes' binaries using RE2 regular expression syntax. | @@ -1217,7 +1223,7 @@ Determines the behavior of a field filter | process | [Process](#tetragon-Process) | | | | color | [string](#string) | | | | refcnt | [google.protobuf.UInt32Value](#google-protobuf-UInt32Value) | | | -| refcnt_ops | [ProcessInternal.RefcntOpsEntry](#tetragon-ProcessInternal-RefcntOpsEntry) | repeated | refcnt_ops is a map of operations to refcnt change keys can be: - "process++": process increased refcnt (i.e. this process starts) - "process--": process decreased refcnt (i.e. this process exits) - "parent++": parent increased refcnt (i.e. a process starts that has this process as a parent) - "parent--": parent decreased refcnt (i.e. a process exits that has this process as a parent) | +| refcnt_ops | [ProcessInternal.RefcntOpsEntry](#tetragon-ProcessInternal-RefcntOpsEntry) | repeated | refcnt_ops is a map of operations to refcnt change keys can be: - "process++": process increased refcnt (i.e. this process starts) - "process--": process decreased refcnt (i.e. this process exits) - "parent++": parent increased refcnt (i.e. a process starts that has this process as a parent) - "parent--": parent decreased refcnt (i.e. a process exits that has this process as a parent) - "ancestor++": ancestor increased refcnt (i.e. a process starts that has this process as an ancestor) - "ancestor--": ancestor decreased refcnt (i.e. a process exits that has this process as an ancestor) | diff --git a/docs/content/en/docs/reference/metrics.md b/docs/content/en/docs/reference/metrics.md index b7d9f6f4506..b19fdd5c273 100644 --- a/docs/content/en/docs/reference/metrics.md +++ b/docs/content/en/docs/reference/metrics.md @@ -103,7 +103,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` @@ -112,7 +112,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 7a27fa4c60d..1295ed39147 100644 --- a/docs/data/tetragon_flags.yaml +++ b/docs/data/tetragon_flags.yaml @@ -75,6 +75,10 @@ options: - name: enable-policy-filter-debug default_value: "false" usage: Enable policy filter debug messages + - name: enable-process-ancestors + 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 38f2a7591f8..7716875461a 100644 --- a/examples/configuration/tetragon.yaml +++ b/examples/configuration/tetragon.yaml @@ -16,6 +16,7 @@ debug: false disable-kprobe-multi: false enable-export-aggregation: false enable-k8s-api: false +enable-process-ancestors: false enable-process-cred: false enable-process-ns: false event-queue-size: 10000