diff --git a/docs/content/en/docs/concepts/tracing-policy/hooks.md b/docs/content/en/docs/concepts/tracing-policy/hooks.md index e5210930bdd..16ab0d962f2 100644 --- a/docs/content/en/docs/concepts/tracing-policy/hooks.md +++ b/docs/content/en/docs/concepts/tracing-policy/hooks.md @@ -212,6 +212,64 @@ spec: This example shows how to use uprobes to hook into the readline function running in all the bash shells. +## LSM BPF + +LSM BPF programs allow runtime instrumentation of the LSM hooks by privileged +users to implement system-wide MAC (Mandatory Access Control) and Audit policies +using eBPF. + +List of LSM hooks which can be instrumented can be found in `security/security.c`. + +To verify if BPF LSM is available use the following command: + +``` +$ cat /boot/config-$(uname -r) | grep BPF_LSM +CONFIG_BPF_LSM=y +``` + +If the output contains `CONFIG_BPF_LSM=y`, BPF LSM is supported. +Then, if provided above conditions are met, use this command to check if BPF LSM is enabled: + +``` +$ cat /sys/kernel/security/lsm +bpf,lockdown,integrity,apparmor +``` + +If the output includes the `bpf`, than BPF LSM is enabled. Otherwise, you can modify `/etc/default/grub`: + +``` +GRUB_CMDLINE_LINUX="lsm=lockdown,integrity,apparmor,bpf" +``` + +Then, update the grub configuration and restart the system. + +The provided example of LSM BPF `TracingPolicy` monitors access to files +`/etc/passwd` and `/etc/shadow` with `/usr/bin/cat` executable. + +```yaml +apiVersion: cilium.io/v1alpha1 +kind: TracingPolicy +metadata: + name: "lsm-file-open" +spec: + lsmhooks: + - hook: "file_open" + args: + - index: 0 + type: "file" + selectors: + - matchBinaries: + - operator: "In" + values: + - "/usr/bin/cat" + matchArgs: + - index: 0 + operator: "Equal" + values: + - "/etc/passwd" + - "/etc/shadow" +``` + ## Arguments Kprobes, uprobes and tracepoints all share a needed arguments fields called `args`. It is a list of diff --git a/docs/content/en/docs/reference/grpc-api.md b/docs/content/en/docs/reference/grpc-api.md index c6fff73fd89..ac6c20067c9 100644 --- a/docs/content/en/docs/reference/grpc-api.md +++ b/docs/content/en/docs/reference/grpc-api.md @@ -549,6 +549,21 @@ loader sensor event triggered for loaded binary/library | path | [string](#string) | | | | buildid | [bytes](#bytes) | | | + + +### ProcessLsm + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| process | [Process](#tetragon-Process) | | | +| parent | [Process](#tetragon-Process) | | | +| 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. | +| 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. | + ### ProcessTracepoint @@ -795,6 +810,7 @@ Capability set to filter over. NOTE: you may specify only ONE set here. | process_tracepoint | [ProcessTracepoint](#tetragon-ProcessTracepoint) | | ProcessTracepoint contains information about the pre-defined tracepoint and the process that invoked them. | | process_loader | [ProcessLoader](#tetragon-ProcessLoader) | | | | process_uprobe | [ProcessUprobe](#tetragon-ProcessUprobe) | | | +| process_lsm | [ProcessLsm](#tetragon-ProcessLsm) | | | | process_throttle | [ProcessThrottle](#tetragon-ProcessThrottle) | | | | test | [Test](#tetragon-Test) | | | | rate_limit_info | [RateLimitInfo](#tetragon-RateLimitInfo) | | | @@ -846,6 +862,7 @@ GetEventsResponse event oneof. | PROCESS_TRACEPOINT | 10 | | | PROCESS_LOADER | 11 | | | PROCESS_UPROBE | 12 | | +| PROCESS_LSM | 13 | | | PROCESS_THROTTLE | 27 | | | TEST | 40000 | | | RATE_LIMIT_INFO | 40001 | | diff --git a/docs/content/en/docs/reference/helm-chart.md b/docs/content/en/docs/reference/helm-chart.md index 687abd12158..83923cea070 100644 --- a/docs/content/en/docs/reference/helm-chart.md +++ b/docs/content/en/docs/reference/helm-chart.md @@ -80,7 +80,7 @@ To use [the values available](#values), with `helm install` or `helm upgrade`, u | tetragon.enableProcessCred | bool | `false` | Enable Capabilities visibility in exec and kprobe events. | | tetragon.enableProcessNs | bool | `false` | Enable Namespaces visibility in exec and kprobe events. | | tetragon.enabled | bool | `true` | | -| tetragon.exportAllowList | string | `"{\"event_set\":[\"PROCESS_EXEC\", \"PROCESS_EXIT\", \"PROCESS_KPROBE\", \"PROCESS_UPROBE\", \"PROCESS_TRACEPOINT\"]}"` | Allowlist for JSON export. For example, to export only process_connect events from the default namespace: exportAllowList: | {"namespace":["default"],"event_set":["PROCESS_EXEC"]} | +| tetragon.exportAllowList | string | `"{\"event_set\":[\"PROCESS_EXEC\", \"PROCESS_EXIT\", \"PROCESS_KPROBE\", \"PROCESS_UPROBE\", \"PROCESS_TRACEPOINT\", \"PROCESS_LSM\"]}"` | Allowlist for JSON export. For example, to export only process_connect events from the default namespace: exportAllowList: | {"namespace":["default"],"event_set":["PROCESS_EXEC"]} | | tetragon.exportDenyList | string | `"{\"health_check\":true}\n{\"namespace\":[\"\", \"cilium\", \"kube-system\"]}"` | Denylist for JSON export. For example, to exclude exec events that look similar to Kubernetes health checks and all the events from kube-system namespace and the host: exportDenyList: | {"health_check":true} {"namespace":["kube-system",""]} | | tetragon.exportFileCompress | bool | `false` | Compress rotated JSON export files. | | tetragon.exportFileMaxBackups | int | `5` | Number of rotated files to retain. | diff --git a/docs/content/en/docs/reference/metrics.md b/docs/content/en/docs/reference/metrics.md index 076bece4e2d..ed089fa40c6 100644 --- a/docs/content/en/docs/reference/metrics.md +++ b/docs/content/en/docs/reference/metrics.md @@ -59,7 +59,7 @@ The total of errors encountered while fetching process exec information from the | label | values | | ----- | ------ | | `error` | `nil_process_pid` | -| `event_type` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_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_parent_info_errors_total` @@ -67,7 +67,7 @@ The total of times we failed to fetch cached parent info for a given event type. | label | values | | ----- | ------ | -| `event_type` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_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_pod_info_errors_total` @@ -75,7 +75,7 @@ The total of times we failed to fetch cached pod info for a given event type. | label | values | | ----- | ------ | -| `event_type` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_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_process_info_errors_total` @@ -83,7 +83,7 @@ The total of times we failed to fetch cached process info for a given event type | label | values | | ----- | ------ | -| `event_type` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_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_retries_total` @@ -425,7 +425,7 @@ The total number of Tetragon events | `binary` | `example-binary` | | `namespace` | `example-namespace` | | `pod ` | `example-pod` | -| `type ` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO` | +| `type ` | `PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_LSM, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO` | | `workload` | `example-workload` | ### `tetragon_policy_events_total`