/docs/concepts/tracing-policy/ Recent content in Tracing Policy on Tetragon - eBPF-based Security Observability and Runtime Enforcement Hugo en /docs/concepts/tracing-policy/example/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/example/ To discover TracingPolicy, let’s understand via an example that will be explained, part by part, in this document: Warning This policy is for illustration purposes only and should not be used to restrict access to certain files. It can be easily bypassed by, for example, using hard links. apiVersion: cilium.io/v1alpha1 kind: TracingPolicy metadata: name: "fd-install" spec: kprobes: - call: "fd_install" syscall: false args: - index: 0 type: "int" - index: 1 type: "file" selectors: - matchArgs: - index: 1 operator: "Equal" values: - "/tmp/tetragon" matchActions: - action: Sigkill The policy checks for file descriptors being created, and sends a SIGKILL signal to any process that creates a file descriptor to a file named /tmp/tetragon. /docs/concepts/tracing-policy/argument_types/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/argument_types/ Each argument definition specifies data type to be retrieved from kernel argument. The list contains simple POD types and several complex kernel objects that are represented by extracted data type. List of described data types: sint8, int8 uint8 sint16, int16 uint16 int, sint32, int32 uint32 long, sint64, int64 ulong, uint64, size_t string skb sock char_buf char_iovec filename fd cred const_buf nop bpf_attr perf_event bpf_map bpf_prog user_namespace capability kiocb iov_iter load_info module syscall64 kernel_cap_t cap_inheritable cap_permitted cap_effective linux_binprm data_loc net_device sockaddr socket file dentry path Note All integer types (int8, uint8, int16, uint16, int32, uint32, int64, uint64) support Equal, NotEqual, GT, LT, and Mask operators in matchArgs or matchData. /docs/concepts/tracing-policy/hooks/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/hooks/ Tetragon can hook into the kernel using kprobes and tracepoints, as well as in user-space programs using uprobes. Users can configure these hook points using the correspodning sections of the TracingPolicy specification (.spec). These hook points include arguments and return values that can be specified using the args and returnArg fields as detailed in the following sections. Warning Hooking a system call can introduce time-of-check to time-of-use (TOCTOU) races when the relevant argument is a pointer to user-space memory. /docs/concepts/tracing-policy/options/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/options/ It’s possible to pass options through spec file as an array of name and value pairs: spec: options: - name: "option-1" value: "True" - name: "option-2" value: "10" Options array is passed and processed by each hook used in the spec file that supports options. At the moment it’s availabe for kprobe and uprobe hooks. Kprobe Options: options for kprobe hooks. Uprobe Options: options for uprobe hooks. Kprobe options disable-kprobe-multi: disable kprobe multi link disable-kprobe-multi This option disables kprobe multi link interface for all the kprobes defined in the spec file. /docs/concepts/tracing-policy/selectors/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/selectors/ Selectors enable per-hook in-kernel BPF filtering and actions. Each selector defines a set of filters as well as a set of (optional) actions to be performed if the selector filters match. Each hook can contain up to 5 selectors. If no selectors are defined on a hook, the default action (Post, i.e., post an event) will be used. Each selector comprises a set of filters: matchArgs: filter on the value of arguments. /docs/concepts/tracing-policy/tags/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/tags/ Tags are optional fields of a Tracing Policy that are used to categorize generated events. Introduction Tags are specified in Tracing policies and will be part of the generated event. apiVersion: cilium.io/v1alpha1 kind: TracingPolicy metadata: name: "file-monitoring-filtered" spec: kprobes: - call: "security_file_permission" message: "Sensitive file system write operation" syscall: false args: - index: 0 type: "file" # (struct file *) used for getting the path - index: 1 type: "int" # 0x04 is MAY_READ, 0x02 is MAY_WRITE selectors: - matchArgs: - index: 0 operator: "Prefix" values: - "/etc" # Writes to sensitive directories - "/boot" - "/lib" - "/lib64" - "/bin" - "/usr/lib" - "/usr/local/lib" - "/usr/local/sbin" - "/usr/local/bin" - "/usr/bin" - "/usr/sbin" - "/var/log" # Writes to logs - "/dev/log" - "/root/. /docs/concepts/tracing-policy/k8s-filtering/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/k8s-filtering/ Motivation Tetragon is configured via TracingPolicies. Broadly speaking, TracingPolicies define what situations Tetragon should react to and how. The what can be, for example, specific system calls with specific argument values. The how defines what action the Tetragon agent should perform when the specified situation occurs. The most common action is generating an event, but there are others (e.g., returning an error without executing the function or killing the corresponding process). /docs/concepts/tracing-policy/mode/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/concepts/tracing-policy/mode/ Beyond monitoring, Tetragon tracing policies include enforcement actions. Configuring the mode of a policy allows you to disable enforcement in a policy, without modifying the policy itself. A tracing policy can be set in two modes: monitoring: enforcement operations are elided enforcement: enforcement operations are respected and performed Using the tetra CLI, you can inspect the mode of each policy. For example: tetra tracingpolicy list Will produce out similar to: