TracingPolicy YAML Schema

TracingPolicy is the YAML format used to define custom detection rules and enforcement policies on the Telovix Sensor. This page is the schema reference. For authoring guidance and examples, see Custom Detection Rules and LSM Hooks.

---

Top-level structure

apiVersion: cilium.io/v1alpha1
kind: TracingPolicy
metadata:
  name: telovix-custom-<name>
spec:
  kprobes:    # or lsmhooks, or uprobes - not combined
    - ...

Field	Value	Notes
apiVersion	cilium.io/v1alpha1	Required. Fixed value.
kind	TracingPolicy	Required. Fixed value.
metadata.name	String	Custom rules authored by operators must start with telovix-custom-. System policies use other prefixes.
spec	Object	Must contain exactly one of kprobes, lsmhooks, or uprobes. Do not mix types in a single policy.

---

kprobes

Use kprobes to hook kernel functions and syscalls. Kprobes can observe function arguments at entry time and return values at exit.

spec:
  kprobes:
    - call: sys_execve
      syscall: true
      args:
        - index: 0
          type: string
      selectors:
        - matchArgs:
            - index: 0
              operator: "Prefix"
              values:
                - "/tmp/"
          matchActions:
            - action: Post

kprobe fields

Field	Required	Description
call	Yes	Kernel function or syscall name. For syscalls, use the short form: sys_execve, sys_openat, sys_write, tcp_connect, etc.
syscall	Yes	true for syscalls (use BPF_PROG_TYPE_KPROBE with syscall=true). false for kernel functions.
args	No	Array of argument capture specifications (see arg fields below).
selectors	No	Array of selector conditions (see selectors below).
returnArg	No	Capture the function return value. Same format as an arg entry. Use index: 0 for the return value.

PREEMPT_RT note: On kernels with PREEMPT_RT patches, kprobes with syscall: true that use BPF_MODIFY_RETURN may fail verification. The sensor detects this at startup and disables affected policies automatically.

---

lsmhooks

Use lsmhooks to attach to Linux Security Module hook points. LSM hooks run before the kernel completes an operation and support the Override action (pre-execution denial). The Override action is not available on kprobes.

spec:
  lsmhooks:
    - hook: bprm_check_security
      args:
        - index: 0
          type: linux_binprm
      selectors:
        - matchArgs:
            - index: 0
              operator: "Postfix"
              values:
                - "suspicious_binary"
          matchActions:
            - action: Override
              argError: -1

Supported LSM hooks

Hook	Description	Arg 0 type
bprm_check_security	Called before a new binary image loads. Fires before process_exec.	linux_binprm
task_fix_setuid	Called on UID/GID changes via setuid/setgid.	(none required)
kernel_read_file	Called when the kernel reads privileged files.	file
file_open	Called when a file is opened.	file

Important: LSM hooks with args must declare at least one arg or matchArgs selectors will silently fail. The bprm_check_security hook requires type: linux_binprm for arg 0, not bprm or any shorthand.

lsmhook fields

Field	Required	Description
hook	Yes	LSM hook name from the supported list above.
args	Yes (for matchArgs)	Argument capture specifications.
selectors	No	Array of selector conditions.

---

uprobes

Use uprobes to hook user-space library functions. The sensor uses uprobes for TLS library instrumentation (OpenSSL, GnuTLS, BoringSSL, Go TLS).

spec:
  uprobes:
    - path: /lib/x86_64-linux-gnu/libssl.so.3
      symbols:
        - SSL_write
      args:
        - index: 0
          type: sock
        - index: 1
          type: char_buf
          sizeArgIndex: 3
        - index: 2
          type: int
      selectors:
        - matchActions:
            - action: Post

uprobe fields

Field	Required	Description
path	Yes	Full path to the user-space library or binary to hook.
symbols	Yes	Array of function symbol names to hook within the binary.
args	No	Argument capture specifications.
selectors	No	Array of selector conditions.
returnArg	No	Capture the return value.

---

Arg types

The args array entries specify which function arguments to capture and how to interpret them.

Field	Required	Description
index	Yes	Zero-based argument position.
type	Yes	Type string from the table below.
sizeArgIndex	Conditional	For char_buf: 1-based index of the arg that holds the buffer size. Value 3 means use arg at index 2 as the size.

Supported arg types

Type	Description
string	Null-terminated string.
int	32-bit signed integer.
uint32	32-bit unsigned integer.
uint64	64-bit unsigned integer.
char_buf	Binary buffer. Requires sizeArgIndex to limit capture length.
sock	Kernel socket structure.
sockaddr	Socket address structure.
file	Kernel file structure (for file_open and kernel_read_file LSM hooks).
linux_binprm	Binary program structure (for bprm_check_security LSM hook).
nop	Skip this argument position (no capture).

---

Selectors

Each entry in the selectors array is evaluated against a captured event. A selector matches when all its conditions match. Multiple selectors in the array are OR-combined: the action fires if any selector matches.

selectors:
  - matchArgs:
      - index: 0
        operator: "Prefix"
        values:
          - "/tmp/"
          - "/dev/shm/"
    matchActions:
      - action: Post

matchArgs

Filter on captured argument values.

Field	Description
index	Argument index to filter on (matches the index from args).
operator	Comparison operator (see table below).
values	Array of string values to compare against. Multiple values are OR-combined within a single matchArgs entry.

Operators

Operator	Description
Equal	Exact match on the full argument value.
Prefix	Argument value starts with one of the given strings.
Postfix	Argument value ends with one of the given strings.
GT	Argument numeric value is greater than the given value.
Mask	Bitwise AND of the argument value with the given mask is non-zero. Used for checking flag fields.

matchActions

Specifies what to do when the selector matches. Place matchActions as a sibling of matchArgs within the same selector block.

selectors:
  - matchArgs:
      - index: 0
        operator: "Equal"
        values:
          - "/usr/bin/curl"
    matchActions:
      - action: Post

---

Actions

Action	Where it works	Fields	Description
Post	kprobes, lsmhooks, uprobes	(none)	Emit the event to the Console. This is the observe-mode action.
Signal	kprobes, uprobes	argSig: <signal_number>	Send a signal to the triggering process. argSig: 9 sends SIGKILL. The process starts but is terminated before it completes.
Override	lsmhooks only	argError: <errno>	Return an error from the kernel call, preventing the operation before the process begins. argError: -1 returns EPERM.

The Override action is exclusive to BPF LSM hooks. Using it in a kprobes section will cause a policy validation error.

Signal example (kill on exec from /tmp)

selectors:
  - matchArgs:
      - index: 0
        operator: "Prefix"
        values:
          - "/tmp/"
    matchActions:
      - action: Signal
        argSig: 9

Override example (block binary execution)

selectors:
  - matchArgs:
      - index: 0
        operator: "Postfix"
        values:
          - "malicious_binary"
    matchActions:
      - action: Override
        argError: -1

---

Limits

Limit	Value	Notes
Max selectors per kprobe/uprobe	5	Tetragon kernel verifier limit (reduced from 8 in older versions). Policies exceeding this are split automatically by the sensor.
Max custom rules per Console	10	Enforced by the Console API.
Max YAML size per rule	16 KB	Enforced by the Console API.
Buffer capture size	~4 KB	BPF stack limit for char_buf captures.

---

Complete kprobe example

The following policy captures sys_write calls to file descriptors when the write size is greater than 8 bytes:

apiVersion: cilium.io/v1alpha1
kind: TracingPolicy
metadata:
  name: telovix-custom-large-write-detect
spec:
  kprobes:
    - call: sys_write
      syscall: true
      args:
        - index: 0
          type: int
        - index: 1
          type: char_buf
          sizeArgIndex: 3
        - index: 2
          type: int
      selectors:
        - matchArgs:
            - index: 2
              operator: "GT"
              values:
                - "8"
          matchActions:
            - action: Post

Complete LSM block example

The following policy blocks execution of any binary whose path ends with cryptominer:

apiVersion: cilium.io/v1alpha1
kind: TracingPolicy
metadata:
  name: telovix-custom-block-cryptominer
spec:
  lsmhooks:
    - hook: bprm_check_security
      args:
        - index: 0
          type: linux_binprm
      selectors:
        - matchArgs:
            - index: 0
              operator: "Postfix"
              values:
                - "cryptominer"
          matchActions:
            - action: Override
              argError: -1

---

Policy naming convention

Operator-authored custom rules must use names starting with telovix-custom-. The Console API validates this prefix on creation. System-managed policies (baseline kprobe policies, TLS uprobe policies, Guardian Profile policies) use different prefixes and are managed automatically by the sensor.

---

Further reading

• Custom Detection Rules
• LSM Hooks Reference
• Kprobes Reference
• Enforcement Reference
• Guardian Profiles and Policies
• Cilium Tetragon - TracingPolicy specification
• Linux kernel documentation - BPF and kprobes