Project: Tetragon (Provisioning / Security & Compliance)
File: grpc-api.md

title: "gRPC API" description: > This reference is generated from the protocol buffer specification and documents the gRPC API of Tetragon. weight: 3 {{< comment >}} This page was generated with github.io/cilium/tetragon/api/export-doc.sh, please do not edit directly. {{< /comment >}} The Tetragon API is an independant Go module that can be found in the Tetragon repository under . The version 1 of this API is defined in . <a name="tetragon-CapabilitiesType"></a> | Name | Number | Description | | - | | -- | | CAPCHOWN | 0 | In a system with the [POSIXCHOWNRESTRICTED] option defined, this overrides the restriction of changing file ownership and group ownership. | | DACOVERRIDE | 1 | Override all DAC access, including ACL execute access if [POSIXACL] is defined. Excluding DAC access covered by CAPLINUX_IMMUTABLE. | | CAPDACREADSEARCH | 2 | Overrides all DAC restrictions regarding read and search on files and directories, including ACL restrictions if [POSIXACL] is defined. Excluding DAC access covered by &#34;$1&#34;LINUX_IMMUTABLE. | | CAPFOWNER | 3 | Overrides all restrictions about allowed operations on files, where file owner ID must be equal to the user ID, except where CAPFSETID is applicable. It doesn&#39;t override MAC and DAC restrictions. | | CAPFSETID | 4 | Overrides the following restrictions that the effective user ID shall match the file owner ID when setting the SISUID and SISGID bits on that file; that the effective group ID (or one of the supplementary group IDs) shall match the file owner ID when setting the SISGID bit on that file; that the SISUID and SISGID bits are cleared on successful return from chown(2) (not implemented). | | CAP_KILL | 5 | Overrides the restriction that the real or effective user ID of a process sending a signal must match the real or effective user ID of the process receiving the signal. | | CAP_SETGID | 6 | Allows forged gids on socket credentials passing. | | CAP_SETUID | 7 | Allows forged pids on socket credentials passing. | | CAP_SETPCAP | 8 | Without VFS support for capabilities: Transfer any capability in your permitted set to any pid, remove any capability in your permitted set from any pid With VFS support for capabilities (neither of above, but) Add any capability from current&#39;s capability bounding set to the current process&#39; inheritable set Allow taking bits out of capability bounding set Allow modification of the securebits for a process | | CAPLINUXIMMUTABLE | 9 | Allow modification of SIMMUTABLE and SAPPEND file attributes | | CAPNETBIND_SERVICE | 10 | Allows binding to ATM VCIs below 32 | | CAPNETBROADCAST | 11 | Allow broadcasting, listen to multicast | | CAPNETADMIN | 12 | Allow activation of ATM control sockets | | CAPNETRAW | 13 | Allow binding to any address for transparent proxying (also via NET_ADMIN) | | CAPIPCLOCK | 14 | Allow mlock and mlockall

doesn&#39;t really have anything to do with IPC) | | CAPIPCOWNER | 15 | Override IPC ownership checks | | CAPSYSMODULE | 16 | Insert and remove kernel modules - modify kernel without limit | | CAPSYSRAWIO | 17 | Allow sending USB messages to any device via /dev/bus/usb | | CAPSYSCHROOT | 18 | Allow use of chroot() | | CAPSYSPTRACE | 19 | Allow ptrace() of any process | | CAPSYSPACCT | 20 | Allow configuration of process accounting | | CAPSYSADMIN | 21 | Allow everything under CAPBPF and CAPPERFMON for backward compatibility | | CAPSYSBOOT | 22 | Allow use of reboot() | | CAPSYSNICE | 23 | Allow setting cpu affinity on other processes | | CAPSYSRESOURCE | 24 | Control memory reclaim behavior | | CAPSYSTIME | 25 | Allow setting the real-time clock | | CAPSYSTTY_CONFIG | 26 | Allow vhangup() of tty | | CAP_MKNOD | 27 | Allow the privileged aspects of mknod() | | CAP_LEASE | 28 | Allow taking of leases on files | | CAPAUDITWRITE | 29 | Allow writing the audit log via unicast netlink socket | | CAPAUDITCONTROL | 30 | Allow configuration of audit via unicast netlink socket | | CAP_SETFCAP | 31 | Set or remove capabilities on files | | CAPMACOVERRIDE | 32 | Override MAC access. The base kernel enforces no MAC policy. An LSM may enforce a MAC policy, and if it does and it chooses to implement capability based overrides of that policy, this is the capability it should use to do so. | | CAPMACADMIN | 33 | Allow MAC configuration or state changes. The base kernel requires no MAC configuration. An LSM may enforce a MAC policy, and if it does and it chooses to implement capability based checks on modifications to that policy or the data required to maintain it, this is the capability it should use to do so. | | CAP_SYSLOG | 34 | Allow configuring the kernel&#39;s syslog (printk behaviour) | | CAPWAKEALARM | 35 | Allow triggering something that will wake the system | | CAPBLOCKSUSPEND | 36 | Allow preventing system suspends | | CAPAUDITREAD | 37 | Allow reading the audit log via multicast netlink socket | | CAPPERFMON | 38 | Allow system performance and observability privileged operations using perfevents, i915_perf and other kernel subsystems | | CAPBPF | 39 | CAPBPF allows the following BPF operations: - Creating all types of BPF maps - Advanced verifier features - Indirect variable access - Bounded loops - BPF to BPF function calls - Scalar precision tracking - Larger complexity limits - Dead code elimination - And potentially other features - Loading BPF Type Format (BTF) data - Retrieve xlated and JITed code of BPF programs - Use bpfspinlock() helper CAPPERFMON relaxes the verifier checks further: - BPF progs can use of pointer-to-integer conversions - speculation attack hardening measures are bypassed - bpfproberead to read arbitrary kernel memory is allowed - bpftraceprintk to print kernel memory is allowed CAPSYSADMIN is required to use bpfprobewriteuser. CAPSYSADMIN is required to iterate system wide loaded programs, maps, links, BTFs and convert their IDs to file descriptors. CAPPERFMON and CAPBPF are required to load tracing programs. CAPNETADMIN and CAP_BPF are required to load networking programs. | | CAPCHECKPOINTRESTORE | 40 | Allow writing to nslastpid | <a name="tetragon-ProcessPrivilegesChanged"></a> Reasons of why the process privileges changed. | Name | Number | Description | | - | | -- | | PRIVILEGESCHANGEDUNSET | 0 | | | PRIVILEGESRAISEDEXECFILECAP | 1 | A privilege elevation happened due to the execution of a binary with file capability sets. The kernel supports associating capability sets with an executable file using `setcap` command. The file capability sets are stored in an extended attribute (see https://man7.org/linux/man-pages/man7/xattr.7.html) named `security.capability`. The file capability sets, in conjunction with the capability sets of the process, determine the process capabilities and privileges after the `execve` system call. For further reference, please check sections `File capability extended attribute versioning` and `Namespaced file capabilities` of the capabilities man pages: https://man7.org/linux/man-pages/man7/capabilities.7.html. The new granted capabilities can be listed inside the `process`

| | PRIVILEGESRAISEDEXECFILESETUID | 2 | A privilege elevation happened due to the execution of a binary with set-user-ID to root. When a process with nonzero UIDs executes a binary with a set-user-ID to root also known as suid-root executable, then the kernel switches the effective user ID to 0 (root) which is a privilege elevation operation since it grants access to resources owned by the root user. The effective user ID is listed inside the `process_credentials` part of the `process` object. For further reading, section `Capabilities and execution of programs by root` of https://man7.org/linux/man-pages/man7/capabilities.7.html. Afterward the kernel recalculates the capability sets of the process and grants all capabilities in the permitted and effective capability sets, except those masked out by the capability bounding set. If the binary also have file capability sets then these bits are honored and the process gains just the capabilities granted by the file capability sets (i.e., not all capabilities, as it would occur when executing a set-user-ID to root binary that does not have any associated file capabilities). This is described in section `Set-user-ID-root programs that have file capabilities` of https://man7.org/linux/man-pages/man7/capabilities.7.html. The new granted capabilities can be listed inside the `process` object. There is one exception for the special treatments of set-user-ID to root execution receiving all capabilities, if the `SecBitNoRoot` bit of the Secure bits is set, then the kernel does not grant any capability. Please check section: `The securebits flags: establishing a capabilities-only environment` of the capabilities man pages: https://man7.org/linux/man-pages/man7/capabilities.7.html | | PRIVILEGESRAISEDEXECFILESETGID | 3 | A privilege elevation happened due to the execution of a binary with set-group-ID to root. When a process with nonzero GIDs executes a binary with a set-group-ID to root, the kernel switches the effective group ID to 0 (root) which is a privilege elevation operation since it grants access to resources owned by the root group. The effective group ID is listed inside the `process_credentials` part of the `process` object. | <a name="tetragon-SecureBitsType"></a> | Name | Number | Description | | - | | -- | | SecBitNotSet | 0 | | | SecBitNoRoot | 1 | When set UID 0 has no special privileges. When unset, inheritance of root-permissions and suid-root executable under compatibility mode is supported. If the effective uid of the new process is 0 then the effective and inheritable bitmasks of the executable file is raised. If the real uid is 0, the effective (legacy) bit of the executable file is raised. | | SecBitNoRootLocked | 2 | Make bit-0 SecBitNoRoot immutable | | SecBitNoSetUidFixup | 4 | When set, setuid to/from uid 0 does not trigger capability-&#34;fixup&#34;. When unset, to provide compatiblility with old programs relying on set*uid to gain/lose privilege, transitions to/from uid 0 cause capabilities to be gained/lost. | | SecBitNoSetUidFixupLocked | 8 | Make bit-2 SecBitNoSetUidFixup immutable | | SecBitKeepCaps | 16 | When set, a process can retain its capabilities even after transitioning to a non-root user (the set-uid fixup suppressed by bit 2). Bit-4 is cleared when a process calls exec(); setting both bit 4 and 5 will create a barrier through exec that no exec()&#39;d child can use this feature again. | | SecBitKeepCapsLocked | 32 | Make bit-4 SecBitKeepCaps immutable | | SecBitNoCapAmbientRaise | 64 | When set, a process cannot add new capabilities to its ambient

| | SecBitNoCapAmbientRaiseLocked | 128 | Make bit-6 SecBitNoCapAmbientRaise immutable | <a name="tetragon_tetragon-proto"></a> <a name="tetragon-BinaryProperties"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | setuid | | | If set then this is the set user ID used for execution | | setgid | | | If set then this is the set group ID used for execution | | privilegeschanged | | repeated | The reasons why this binary execution changed privileges. Usually this happens when the process executes a binary with the set-user-ID to root or file capability sets. The final granted privileges can be listed inside the `processcredentials` or capabilities fields part of of the `process` object. | | file | | | File properties in case the executed binary is: 1. An anonymous shared memory file https://man7.org/linux/man-pages/man7/shmoverview.7.html. 2. An anonymous file obtained with memfd API https://man7.org/linux/man-pages/man2/memfdcreate.2.html. 3. Or it was deleted from the file system. | <a name="tetragon-Capabilities"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | permitted | | repeated | Permitted set indicates what capabilities the process can use. This is a limiting superset for the effective capabilities that the thread may assume. It is also a limiting superset for the capabilities that may be added to the inheritable set by a thread without the CAP_SETPCAP in its effective set. | | effective | | repeated | Effective set indicates what capabilities are active in a process. This is the set used by the kernel to perform permission checks for the thread. | | inheritable | | repeated | Inheritable set indicates which capabilities will be inherited by the current process when running as a root user. | <a name="tetragon-Container"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | id | | | Identifier of the container. | | name | | | Name of the container. | | image | | | Image of the container. | | start_time | | | Start time of the container. | | pid | | | Process identifier in the container namespace. | | maybeexecprobe | | | If this is set true, it means that the process might have been originated from a Kubernetes exec probe. For this field to be true, the following must be true: 1. The binary field matches the first element of the exec command list for either liveness or readiness probe excluding the basename. For example, &#34;/bin/ls&#34; and &#34;ls&#34; are considered a match. 2. The arguments field exactly matches the rest of the exec command list. | <a name="tetragon-CreateContainer"></a> CreateContainer informs the agent that a container was created This is intented to be used by OCI hooks (but not limited to them) and corresponds to the CreateContainer hook: https://github.com/opencontainers/runtime-spec/blob/main/config.md#createcontainer-hooks. | Field | Type | Label | Description | | -- | - | -- | -- | | cgroupsPath | | | cgroupsPath is the cgroups path for the container. The path is expected to be relative to the cgroups mountpoint. See: https://github.com/opencontainers/runtime-spec/blob/58ec43f9fc39e0db229b653ae98295bfde74aeab/specs-go/config.go#L174 | | rootDir | | | rootDir is the absolute path of the root directory of the container. See: https://github.com/opencontainers/runtime-spec/blob/main/specs-go/config.go#L174 | | annotations | | repeated | annotations are the run-time annotations for the container

https://github.com/opencontainers/runtime-spec/blob/main/config.md#annotations | | containerName | | | containerName is the name of the container | <a name="tetragon-CreateContainer-AnnotationsEntry"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | key | | | | | value | | | | <a name="tetragon-FileProperties"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | inode | | | Inode of the file | | path | | | Path of the file | <a name="tetragon-GetHealthStatusRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | event_set | | repeated | | <a name="tetragon-GetHealthStatusResponse"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | health_status | | repeated | | <a name="tetragon-HealthStatus"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | event | | | | | status | | | | | details | | | | <a name="tetragon-Image"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | id | | | Identifier of the container image composed of the registry path and the sha256. | | name | | | Name of the container image composed of the registry path and the tag. | <a name="tetragon-InodeProperties"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | number | | | The inode number | | links | | | The inode links on the file system. If zero means the file is only in memory | <a name="tetragon-KernelModule"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | Kernel module name | | signatureok | | | If true the module signature was verified successfully. Depends on kernels compiled with CONFIGMODULE_SIG option, for details please read: https://www.kernel.org/doc/Documentation/admin-guide/module-signing.rst | | tainted | | repeated | The module tainted flags that will be applied on the kernel. For further details please read: https://docs.kernel.org/admin-guide/tainted-kernels.html | <a name="tetragon-KprobeArgument"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | string_arg | | | | | int_arg | | | | | skb_arg | | | | | size_arg | | | | | bytes_arg | | | | | path_arg | | | | | file_arg | | | | | truncatedbytesarg | | | | | sock_arg | | | | | cred_arg | | | | | long_arg | | | | | bpfattrarg | | | | | perfeventarg | | | | | bpfmaparg | | | | | uint_arg | | | | | usernamespacearg | | | Deprecated. | | capability_arg | | | | | processcredentialsarg | | | | | usernsarg | | | | | module_arg | | | | | kernelcapt_arg | | | Capabilities in hexadecimal format. | | capinheritablearg | | | Capabilities inherited by a forked process in hexadecimal format. | | cappermittedarg | | | Capabilities that are currently permitted in hexadecimal format. | | capeffectivearg | | | Capabilities that are actually used in hexadecimal

| | linuxbinprmarg | | | | | netdevarg | | | | | label | | | | <a name="tetragon-KprobeBpfAttr"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | ProgType | | | | | InsnCnt | | | | | ProgName | | | | <a name="tetragon-KprobeBpfMap"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | MapType | | | | | KeySize | | | | | ValueSize | | | | | MaxEntries | | | | | MapName | | | | <a name="tetragon-KprobeCapability"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | value | | | | | name | | | | <a name="tetragon-KprobeCred"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | permitted | | repeated | | | effective | | repeated | | | inheritable | | repeated | | <a name="tetragon-KprobeFile"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | mount | | | | | path | | | | | flags | | | | | permission | | | | <a name="tetragon-KprobeLinuxBinprm"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | path | | | | | flags | | | | | permission | | | | <a name="tetragon-KprobeNetDev"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-KprobePath"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | mount | | | | | path | | | | | flags | | | | | permission | | | | <a name="tetragon-KprobePerfEvent"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | KprobeFunc | | | | | Type | | | | | Config | | | | | ProbeOffset | | | | <a name="tetragon-KprobeSkb"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | hash | | | | | len | | | | | priority | | | | | mark | | | | | saddr | | | | | daddr | | | | | sport | | | | | dport | | | | | proto | | | | | secpathlen | | | | | secpatholen | | | | | protocol | | | | | family | | | | <a name="tetragon-KprobeSock"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | family | | | | | type | | | | | protocol | | | | | mark | | | | | priority | | | | | saddr | | | | | daddr | | | | | sport | | | | | dport | | | | | cookie | | | | | state | | | | <a name="tetragon-KprobeTruncatedBytes"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | bytes_arg | | | | | orig_size | | | | <a name="tetragon-KprobeUserNamespace"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | level | | | | | owner | | | | | group | | | | | ns | | | | <a name="tetragon-Namespace"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | inum | | | Inode number of the namespace. | | is_host | | | Indicates if namespace belongs to host. | <a name="tetragon-Namespaces"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | uts | | | Hostname and NIS domain

| | ipc | | | System V IPC, POSIX message queues. | | mnt | | | Mount points. | | pid | | | Process IDs. | | pidforchildren | | | Process IDs for children processes. | | net | | | Network devices, stacks, ports, etc. | | time | | | Boot and monotonic clocks. | | timeforchildren | | | Boot and monotonic clocks for children processes. | | cgroup | | | Cgroup root directory. | | user | | | User and group IDs. | <a name="tetragon-Pod"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | namespace | | | Kubernetes namespace of the Pod. | | name | | | Name of the Pod. | | container | | | Container of the Pod from which the process that triggered the event originates. | | pod_labels | | repeated | Contains all the labels of the pod. | | workload | | | Kubernetes workload of the Pod. | | workload_kind | | | Kubernetes workload kind (e.g. &#34;Deployment&#34;, &#34;DaemonSet&#34;) of the Pod. | <a name="tetragon-Pod-PodLabelsEntry"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | key | | | | | value | | | | <a name="tetragon-Process"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | exec_id | | | Exec ID uniquely identifies the process over time across all the nodes in the cluster. | | pid | | | Process identifier from host PID namespace. | | uid | | | User identifier associated with the process. | | cwd | | | Current working directory of the process. | | binary | | | Absolute path of the executed binary. | | arguments | | | Arguments passed to the binary at execution. | | flags | | | Flags are for debugging purposes only and should not be considered a reliable source of information. They hold various information about which syscalls generated events, use of internal Tetragon buffers, errors and more. - `execve` This event is generated by an execve syscall for a new process. See procFs for the other option. A correctly formatted event should either set execve or procFS (described next). - `procFS` This event is generated from a proc interface. This happens at Tetragon init when existing processes are being loaded into Tetragon event buffer. All events should have either execve or procFS set. - `truncFilename` Indicates a truncated processes filename because the buffer size is too small to contain the process filename. Consider increasing buffer size to avoid this. - `truncArgs` Indicates truncated the processes arguments because the buffer size was too small to contain all exec args. Consider increasing buffer size to avoid this. - `taskWalk` Primarily useful for debugging. Indicates a walked process hierarchy to find a parent process in the Tetragon buffer. This may happen when we did not receive an exec event for the immediate parent of a process. Typically means we are looking at a fork that in turn did another fork we don&#39;t currently track fork events exactly and instead push an event with the original parent exec data. This flag can provide this insight into the event if needed. - `miss` An error flag indicating we could not find parent info in the Tetragon event buffer. If this is set it should be reported to Tetragon developers for

Tetragon will do its best to recover information about the process from available kernel data structures instead of using cached info in this case. However, args will not be available. - `needsAUID` An internal flag for Tetragon to indicate the audit has not yet been resolved. The BPF hooks look at this flag to determine if probing the audit system is necessary. - `errorFilename` An error flag indicating an error happened while reading the filename. If this is set it should be reported to Tetragon developers for debugging. - `errorArgs` An error flag indicating an error happened while reading the process args. If this is set it should be reported to Tetragon developers for debugging - `needsCWD` An internal flag for Tetragon to indicate the current working directory has not yet been resolved. The Tetragon hooks look at this flag to determine if probing the CWD is necessary. - `noCWDSupport` Indicates that CWD is removed from the event because the buffer size is too small. Consider increasing buffer size to avoid this. - `rootCWD` Indicates that CWD is the root directory. This is necessary to inform readers the CWD is not in the event buffer and is &#39;/&#39; instead. - `errorCWD` An error flag indicating an error occurred while reading the CWD of a process. If this is set it should be reported to Tetragon developers for debugging. - `clone` Indicates the process issued a clone before exec. This is the general flow to exec a new process, however its possible to replace the current process with a new process by doing an exec* without a clone. In this case the flag will be omitted and the same PID will be used by the kernel for both the old process and the newly exec&#39;d process. | | start_time | | | Start time of the execution. | | auid | | | Audit user ID, this ID is assigned to a user upon login and is inherited by every process even when the user&#39;s identity changes. For example, by switching user accounts with su - john. | | pod | | | Information about the the Kubernetes Pod where the event originated. | | docker | | | The 15 first digits of the container ID. | | parentexecid | | | Exec ID of the parent process. | | refcnt | | | Reference counter from the Tetragon process cache. | | cap | | | Set of capabilities that define the permissions the process can execute with. | | ns | | | Linux namespaces of the process, disabled by default, can be enabled by the `--enable-process-ns` flag. | | tid | | | Thread ID, note that for the thread group leader, tid is equal to pid. | | process_credentials | | | Process credentials | | binary_properties | | | Executed binary properties. This field is only available on ProcessExec events. | | user | | | UserRecord contains user information about the event. UserRecord is only supported when i) Tetragon is running as a systemd service or directly on the host, and ii) when `--username-metadata` is set to &#34;unix&#34;. In this case, the information is retrieved from the traditional user database `/etc/passwd` and no name services lookups are performed. The resolution will only be attempted for processes in the host namespace. Note that this resolution happens in user-space, which means that mapping might have changed between the in-kernel BPF hook being executed and the username

| <a name="tetragon-ProcessCredentials"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | uid | | | The real user ID | | gid | | | The real group ID | | euid | | | The effective user ID | | egid | | | The effective group ID | | suid | | | The saved user ID | | sgid | | | The saved group ID | | fsuid | | | the filesystem user ID | | fsgid | | | The filesystem group ID | | securebits | | repeated | Secure management flags | | caps | | | Set of capabilities that define the permissions the process can execute with. | | user_ns | | | User namespace where the UIDs, GIDs and capabilities are relative to. | <a name="tetragon-ProcessExec"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | process | | | Process that triggered the exec. | | parent | | | Immediate parent of the process. | | ancestors | | repeated | Ancestors of the process beyond the immediate parent. | <a name="tetragon-ProcessExit"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | process | | | Process that triggered the exit. | | parent | | | Immediate parent of the process. | | signal | | | 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 | | | Status code on process exit. For example, the status code can indicate if an error was encountered or the program exited successfully. | | time | | | Date and time of the event. | <a name="tetragon-ProcessKprobe"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | process | | | Process that triggered the kprobe. | | parent | | | Immediate parent of the process. | | function_name | | | Symbol on which the kprobe was attached. | | args | | repeated | Arguments definition of the observed kprobe. | | return | | | Return value definition of the observed kprobe. | | action | | | Action performed when the kprobe matched. | | kernelstacktrace | | repeated | Kernel stack trace to the call. | | policy_name | | | Name of the Tracing Policy that created that kprobe. | | return_action | | | Action performed when the return kprobe executed. | | message | | | Short message of the Tracing Policy to inform users what is going on. | | tags | | repeated | Tags of the Tracing Policy to categorize the event. | | userstacktrace | | repeated | User-mode stack trace to the call. | <a name="tetragon-ProcessLoader"></a> loader sensor event triggered for loaded binary/library | Field | Type | Label | Description | | -- | - | -- | -- | | process | | | | | path | | | | | buildid | | | | <a name="tetragon-ProcessTracepoint"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | process | | | Process that triggered the tracepoint. | | parent | | | Immediate parent of the process. | | subsys | | | Subsystem of the

| | event | | | Event of the subsystem. | | args | | repeated | Arguments definition of the observed tracepoint. TODO: once we implement all we want, rename KprobeArgument to GenericArgument | | policy_name | | | Name of the policy that created that tracepoint. | | action | | | Action performed when the tracepoint matched. | | message | | | Short message of the Tracing Policy to inform users what is going on. | | tags | | repeated | Tags of the Tracing Policy to categorize the event. | <a name="tetragon-ProcessUprobe"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | process | | | | | parent | | | | | path | | | | | symbol | | | | | policy_name | | | Name of the policy that created that uprobe. | | message | | | Short message of the Tracing Policy to inform users what is going on. | | args | | repeated | Arguments definition of the observed uprobe. | | tags | | repeated | Tags of the Tracing Policy to categorize the event. | <a name="tetragon-RuntimeHookRequest"></a> RuntimeHookRequest synchronously propagates information to the agent about run-time state. | Field | Type | Label | Description | | -- | - | -- | -- | | createContainer | | | | <a name="tetragon-RuntimeHookResponse"></a> <a name="tetragon-StackTraceEntry"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | address | | | linear address of the function in kernel or user space. | | offset | | | offset is the offset into the native instructions for the function. | | symbol | | | symbol is the symbol name of the function. | | module | | | module path for user space addresses. | <a name="tetragon-Test"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | arg0 | | | | | arg1 | | | | | arg2 | | | | | arg3 | | | | <a name="tetragon-UserNamespace"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | level | | | Nested level of the user namespace. Init or host user namespace is at level 0. | | uid | | | The owner user ID of the namespace | | gid | | | The owner group ID of the namepace. | | ns | | | The user namespace details that include the inode number of the namespace. | <a name="tetragon-UserRecord"></a> User records | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | The UNIX username for this record. Corresponds to `pwname` field of and the `spnamp` field of . | <a name="tetragon-HealthStatusResult"></a> | Name | Number | Description | | - | | -- | | HEALTHSTATUSUNDEF | 0 | | | HEALTHSTATUSRUNNING | 1 | | | HEALTHSTATUSSTOPPED | 2 | | | HEALTHSTATUSERROR | 3 | | <a name="tetragon-HealthStatusType"></a> | Name | Number | Description | | - | | -- | | HEALTHSTATUSTYPE_UNDEF | 0 | | | HEALTHSTATUSTYPE_STATUS | 1 | | <a name="tetragon-KprobeAction"></a> | Name | Number | Description | | - | | -- | | KPROBEACTIONUNKNOWN | 0 | Unknown action | | KPROBEACTIONPOST | 1 | Post action creates an event (default

| | KPROBEACTIONFOLLOWFD | 2 | Post action creates a mapping between file descriptors and file names. | | KPROBEACTIONSIGKILL | 3 | Sigkill action synchronously terminates the process. | | KPROBEACTIONUNFOLLOWFD | 4 | Post action removes a mapping between file descriptors and file names. | | KPROBEACTIONOVERRIDE | 5 | Override action modifies the return value of the call. | | KPROBEACTIONCOPYFD | 6 | Post action dupplicates a mapping between file descriptors and file names. | | KPROBEACTIONGETURL | 7 | GetURL action issue an HTTP Get request against an URL from userspace. | | KPROBEACTIONDNSLOOKUP | 8 | GetURL action issue a DNS lookup against an URL from userspace. | | KPROBEACTIONNOPOST | 9 | NoPost action suppresses the transmission of the event to userspace. | | KPROBEACTIONSIGNAL | 10 | Signal action sends specified signal to the process. | | KPROBEACTIONTRACKSOCK | 11 | TrackSock action tracks socket. | | KPROBEACTIONUNTRACKSOCK | 12 | UntrackSock action un-tracks socket. | | KPROBEACTIONNOTIFYENFORCER | 13 | NotifyEnforcer action notifies killer sensor. | <a name="tetragon-TaintedBitsType"></a> Tainted bits to indicate if the kernel was tainted. For further details: https://docs.kernel.org/admin-guide/tainted-kernels.html | Name | Number | Description | | - | | -- | | TAINT_UNSET | 0 | | | TAINTPROPRIETARYMODULE | 1 | A proprietary module was loaded. | | TAINTFORCEDMODULE | 2 | A module was force loaded. | | TAINTFORCEDUNLOAD_MODULE | 4 | A module was force unloaded. | | TAINTSTAGEDMODULE | 1024 | A staging driver was loaded. | | TAINTOUTOFTREEMODULE | 4096 | An out of tree module was loaded. | | TAINTUNSIGNEDMODULE | 8192 | An unsigned module was loaded. Supported only on kernels built with CONFIGMODULESIG option. | | TAINTKERNELLIVEPATCHMODULE | 32768 | The kernel has been live patched. | | TAINTTESTMODULE | 262144 | Loading a test module. | <a name="tetragon_events-proto"></a> <a name="tetragon-AggregationInfo"></a> AggregationInfo contains information about aggregation results. | Field | Type | Label | Description | | -- | - | -- | -- | | count | | | Total count of events in this aggregation time window. | <a name="tetragon-AggregationOptions"></a> AggregationOptions defines configuration options for aggregating events. | Field | Type | Label | Description | | -- | - | -- | -- | | window_size | | | Aggregation window size. Defaults to 15 seconds if this field is not set. | | channelbuffersize | | | Size of the buffer for the aggregator to receive incoming events. If the buffer becomes full, the aggregator will log a warning and start dropping incoming events. | <a name="tetragon-CapFilter"></a> Filter over a set of Linux process capabilities. See `message Capabilities` for more info. WARNING: Multiple sets are ANDed. For example, if the permitted filter matches, but the effective filter does not, the filter will NOT match. | Field | Type | Label | Description | | -- | - | -- | -- | | permitted | | | Filter over the set of permitted capabilities. | | effective | | | Filter over the set of effective capabilities. | | inheritable | | | Filter over the set of inheritable capabilities. | <a name="tetragon-CapFilterSet"></a> Capability set to filter over. NOTE: you may specify only ONE set here. | Field | Type | Label | Description | | -- | - | -- | -- | | any | | repeated | Match if the capability set contains any of the capabilities defined in this

| | all | | repeated | Match if the capability set contains all of the capabilities defined in this filter. | | exactly | | repeated | Match if the capability set exactly matches all of the capabilities defined in this filter. | | none | | repeated | Match if the capability set contains none of the capabilities defined in this filter. | <a name="tetragon-FieldFilter"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | event_set | | repeated | Event types to filter or undefined to filter over all event types. | | fields | | | Fields to include or exclude. | | action | | | Whether to include or exclude fields. | | inverteventset | | | Whether or not the event set filter should be inverted. | <a name="tetragon-Filter"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | binary_regex | | repeated | | | namespace | | repeated | | | health_check | | | | | pid | | repeated | | | pid_set | | repeated | Filter by the PID of a process and any of its descendants. Note that this filter is intended for testing and development purposes only and should not be used in production. In particular, PID cycling in the OS over longer periods of time may cause unexpected events to pass this filter. | | event_set | | repeated | | | pod_regex | | repeated | Filter by process.pod.name field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | arguments_regex | | repeated | Filter by process.arguments field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax | | labels | | repeated | Filter events by pod labels using Kubernetes label selector syntax: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors Note that this filter never matches events without the pod field (i.e. host process events). | | policy_names | | repeated | Filter events by tracing policy names | | capabilities | | | Filter events by Linux process capability | <a name="tetragon-GetEventsRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | allowlist | | repeated | allowlist specifies a list of filters to apply to only return certain events. If multiple filters are specified, at least one of them has to match for an event to be included in the results. | | denylist | | repeated | denylist specifies a list of filters to apply to exclude certain events from the results. If multiple filters are specified, at least one of them has to match for an event to be excluded. If both allowlist and denylist are specified, the results contain the set difference allowlist - denylist. | | aggregationoptions | | | aggregationoptions configures aggregation options for this request. If this field is not set, responses will not be aggregated. Note that currently only processaccept and processconnect events are aggregated. Other events remain unaggregated. | | field_filters | | repeated | Fields to include or exclude for events in the GetEventsResponse. Omitting this field implies that all fields will be included. Exclusion always takes precedence over inclusion in the case of conflicts. | <a name="tetragon-GetEventsResponse"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | process_exec | | | ProcessExec event includes information about the execution of binaries and other related process metadata. | | process_exit | | | ProcessExit event indicates how and when a process

| | process_kprobe | | | ProcessKprobe event contains information about the pre-defined functions and the process that invoked them. | | process_tracepoint | | | ProcessTracepoint contains information about the pre-defined tracepoint and the process that invoked them. | | process_loader | | | | | process_uprobe | | | | | process_throttle | | | | | test | | | | | ratelimitinfo | | | | | node_name | | | Name of the node where this event was observed. | | time | | | Timestamp at which this event was observed. For an aggregated response, this field to set to the timestamp at which the event was observed for the first time in a given aggregation time window. | | aggregationinfo | | | aggregationinfo contains information about aggregation results. This field is set only for aggregated responses. | <a name="tetragon-ProcessThrottle"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | type | | | Throttle type | | cgroup | | | Cgroup name | <a name="tetragon-RateLimitInfo"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | numberofdroppedprocessevents | | | | <a name="tetragon-RedactionFilter"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | match | | repeated | Deprecated. Deprecated, do not use. | | redact | | repeated | RE2 regular expressions to use for redaction. Strings inside capture groups are redacted. | | binary_regex | | repeated | RE2 regular expression to match binary name. If supplied, redactions will only be applied to matching processes. | <a name="tetragon-EventType"></a> Represents the type of a Tetragon event. NOTE: EventType constants must be in sync with the numbers used in the GetEventsResponse event

| Name | Number | Description | | - | | -- | | UNDEF | 0 | | | PROCESS_EXEC | 1 | | | PROCESS_EXIT | 5 | | | PROCESS_KPROBE | 9 | | | PROCESS_TRACEPOINT | 10 | | | PROCESS_LOADER | 11 | | | PROCESS_UPROBE | 12 | | | PROCESS_THROTTLE | 27 | | | TEST | 40000 | | | RATELIMITINFO | 40001 | | <a name="tetragon-FieldFilterAction"></a> Determines the behavior of a field filter | Name | Number | Description | | - | | -- | | INCLUDE | 0 | | | EXCLUDE | 1 | | <a name="tetragon-ThrottleType"></a> | Name | Number | Description | | - | | -- | | THROTTLE_UNKNOWN | 0 | | | THROTTLE_START | 1 | | | THROTTLE_STOP | 2 | | <a name="tetragon_stack-proto"></a> <a name="tetragon-StackAddress"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | address | | | | | symbol | | | | <a name="tetragon-StackTrace"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | addresses | | repeated | | <a name="tetragon-StackTraceLabel"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | key | | | | | count | | | | <a name="tetragon-StackTraceNode"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | address | | | | | count | | | | | labels | | repeated | | | children | | repeated | | <a name="tetragon_sensors-proto"></a> <a name="tetragon-AddTracingPolicyRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | yaml | | | | <a name="tetragon-AddTracingPolicyResponse"></a> <a name="tetragon-DeleteTracingPolicyRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-DeleteTracingPolicyResponse"></a> <a name="tetragon-DisableSensorRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-DisableSensorResponse"></a> <a name="tetragon-DisableTracingPolicyRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-DisableTracingPolicyResponse"></a> <a name="tetragon-EnableSensorRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-EnableSensorResponse"></a> <a name="tetragon-EnableTracingPolicyRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-EnableTracingPolicyResponse"></a> <a name="tetragon-GetStackTraceTreeRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-GetStackTraceTreeResponse"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | root | | | | <a name="tetragon-GetVersionRequest"></a> <a name="tetragon-GetVersionResponse"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | version | | | | <a name="tetragon-ListSensorsRequest"></a> <a name="tetragon-ListSensorsResponse"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | sensors | | repeated | | <a name="tetragon-ListTracingPoliciesRequest"></a> <a name="tetragon-ListTracingPoliciesResponse"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | policies | | repeated | | <a name="tetragon-RemoveSensorRequest"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | | <a name="tetragon-RemoveSensorResponse"></a> <a name="tetragon-SensorStatus"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | name | | | name is the name of the sensor | | enabled | | | enabled marks whether the sensor is enabled | | collection | | | collection is the collection the sensor belongs to (typically a tracing policy) | <a name="tetragon-TracingPolicyStatus"></a> | Field | Type | Label | Description | | -- | - | -- | -- | | id | | | id is the id of the policy | | name | | | name is the name of the policy | | namespace | | | namespace is the namespace of the policy (or empty of the policy is global) | | info | | | info is additional information about the policy | | sensors | | repeated | sensors loaded in the scope of this policy | | enabled | | | Deprecated. indicating if the policy is enabled. Deprecated: use &#39;state&#39;

| | filter_id | | | filter ID of the policy used for k8s filtering | | error | | | potential error of the policy | | state | | | current state of the tracing policy | <a name="tetragon-TracingPolicyState"></a> | Name | Number | Description | | - | | -- | | TPSTATEUNKNOWN | 0 | unknown state | | TPSTATEENABLED | 1 | loaded and enabled | | TPSTATEDISABLED | 2 | loaded but disabled | | TPSTATELOAD_ERROR | 3 | failed to load | | TPSTATEERROR | 4 | failed during lifetime | <a name="tetragon-FineGuidanceSensors"></a> | Method Name | Request Type | Response Type | Description | | -- | | - | | | GetEvents | | stream | | | GetHealth | | | | | AddTracingPolicy | | | | | DeleteTracingPolicy | | | | | RemoveSensor | | | | | ListTracingPolicies | | | | | EnableTracingPolicy | | | | | DisableTracingPolicy | | | | | ListSensors | | | | | EnableSensor | | | | | DisableSensor | | | | | GetStackTraceTree | | | | | GetVersion | | | | | RuntimeHook | | | | | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | | -- | -- | | - | | -- | -- | | - | | <a name="double" /> double | | double | double | float | float64 | double | float | Float | | <a name="float" /> float | | float | float | float | float32 | float | float | Float | | <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | | <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | | <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | | <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | | <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | | <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | | <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as