This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Reference

Low level reference documentation for Tetragon

1: Daemon Configuration
2: Helm chart
3: gRPC API
4: Metrics

1 - Daemon Configuration

Explore Tetragon options and configuration mechanisms.

Tetragon default controlling settings are set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. This document lists those controlling settings and how they can be set as a CLI arguments or as configuration options from YAML files.

Options

The following table list all Tetragon daemon available options and is automatically generated using the tetragon binary --generate-docs flag. The same information can also be retrieved using --help.

Flag	Usage	Default Value
`--bpf-lib`	Location of Tetragon libs (btf and bpf files)	`/var/lib/tetragon/`
`--btf`	Location of btf
`--cgroup-rate`	Base sensor events cgroup rate <events,interval> disabled by default ('1000/1s' means rate 1000 events per second
`--config-dir`	Configuration directory that contains a file for each option
`--cpuprofile`	Store CPU profile into provided file
`--data-cache-size`	Size of the data events cache	`1024`
`--debug`	Enable debug messages. Equivalent to '--log-level=debug'	`false`
`--disable-kprobe-multi`	Allow to disable kprobe multi interface	`false`
`--enable-export-aggregation`	Enable JSON export aggregation	`false`
`--enable-k8s-api`	Access Kubernetes API to associate Tetragon events with Kubernetes pods	`false`
`--enable-msg-handling-latency`	Enable metrics for message handling latency	`false`
`--enable-pid-set-filter`	Enable pidSet export filters. Not recommended for production use	`false`
`--enable-pod-info`	Enable PodInfo custom resource	`false`
`--enable-policy-filter`	Enable policy filter code (beta)	`false`
`--enable-policy-filter-debug`	Enable policy filter debug messages	`false`
`--enable-process-ancestors`	Include ancestors in process exec events	`true`
`--enable-process-cred`	Enable process_cred events	`false`
`--enable-process-ns`	Enable namespace information in process_exec and process_kprobe events	`false`
`--enable-tracing-policy-crd`	Enable TracingPolicy and TracingPolicyNamespaced custom resources	`true`
`--event-queue-size`	Set the size of the internal event queue.	`10000`
`--export-aggregation-buffer-size`	Aggregator channel buffer size	`10000`
`--export-aggregation-window-size`	JSON export aggregation time window	`15s`
`--export-allowlist`	JSON export allowlist
`--export-denylist`	JSON export denylist
`--export-file-compress`	Compress rotated JSON export files	`false`
`--export-file-max-backups`	Number of rotated JSON export files to retain	`5`
`--export-file-max-size-mb`	Size in MB for rotating JSON export files	`10`
`--export-file-perm`	Access permissions on JSON export files	`600`
`--export-file-rotation-interval`	Interval at which to rotate JSON export files in addition to rotating them by size	`0s`
`--export-filename`	Filename for JSON export. Disabled by default
`--export-rate-limit`	Rate limit (per minute) for event export. Set to -1 to disable	`-1`
`--expose-kernel-addresses`	Expose real kernel addresses in events stack traces	`false`
`--expose-stack-addresses`	Expose real linear addresses in events stack traces	`false`
`--field-filters`	Field filters for event exports
`--force-large-progs`	Force loading large programs, even in kernels with < 5.3 versions	`false`
`--force-small-progs`	Force loading small programs, even in kernels with >= 5.3 versions	`false`
`--generate-docs`	Generate documentation in YAML format to stdout	`false`
`--gops-address`	gops server address (e.g. 'localhost:8118'). Disabled by default
`--help`	help for tetragon	`false`
`--k8s-kubeconfig-path`	Absolute path of the kubernetes kubeconfig file
`--kernel`	Kernel version
`--kmods`	List of kernel modules to load symbols from	`[]`
`--log-format`	Set log format	`text`
`--log-level`	Set log level	`info`
`--memprofile`	Store MEM profile into provided file
`--metrics-label-filter`	Comma-separated list of enabled metrics labels. Unknown labels will be ignored.	`namespace,workload,pod,binary`
`--metrics-server`	Metrics server address (e.g. ':2112'). Disabled by default
`--netns-dir`	Network namespace dir	`/var/run/docker/netns/`
`--pprof-addr`	Profile via pprof http
`--process-cache-size`	Size of the process cache	`65536`
`--procfs`	Location of procfs to consume existing PIDs	`/proc/`
`--rb-queue-size`	Set size of channel between ring buffer and sensor go routines (default 65k, allows K/M/G suffix)	`65535`
`--rb-size`	Set perf ring buffer size for single cpu (default 65k, allows K/M/G suffix)	`0`
`--rb-size-total`	Set perf ring buffer size in total for all cpus (default 65k per cpu, allows K/M/G suffix)	`0`
`--redaction-filters`	Redaction filters for events
`--release-pinned-bpf`	Release all pinned BPF programs and maps in Tetragon BPF directory. Enabled by default. Set to false to disable	`true`
`--server-address`	gRPC server address (e.g. 'localhost:54321' or 'unix:///var/run/tetragon/tetragon.sock'	`localhost:54321`
`--tracing-policy`	Tracing policy file to load at startup
`--tracing-policy-dir`	Directory from where to load Tracing Policies	`/etc/tetragon/tetragon.tp.d`
`--username-metadata`	Resolve UIDs to user names for processes running in host namespace	`disabled`
`--verbose`	set verbosity level for eBPF verifier dumps. Pass 0 for silent, 1 for truncated logs, 2 for a full dump	`0`

Configuration precedence

Tetragon controlling settings can also be loaded from YAML configuration files according to this order:

From the drop-in configuration snippets inside the following directories where each filename maps to one controlling setting and the content of the file to its corresponding value:
- /usr/lib/tetragon/tetragon.conf.d/*
- /usr/local/lib/tetragon/tetragon.conf.d/*
From the configuration file /etc/tetragon/tetragon.yaml if available, overriding previous settings.
From the drop-in configuration snippets inside /etc/tetragon/tetragon.conf.d/*, similarly overriding previous settings.
If the config-dir setting is set, Tetragon loads its settings from the files inside the directory pointed by this option, overriding previous controlling settings. The config-dir is also part of Kubernetes ConfigMap.

When reading configuration from directories, each filename maps to one controlling setting. If the same controlling setting is set multiple times, then the last value or content of that file overrides the previous ones.

To summarize the configuration precedence:

Drop-in directory pointed by --config-dir.
Drop-in directory /etc/tetragon/tetragon.conf.d/*.
Configuration file /etc/tetragon/tetragon.yaml.
Drop-in directories:
- /usr/local/lib/tetragon/tetragon.conf.d/*
- /usr/lib/tetragon/tetragon.conf.d/*

Note

To clear a controlling setting that was set before, set it again to an empty value.

Package managers can customize the configuration by installing drop-ins under /usr/. Configurations in /etc/tetragon/ are strictly reserved for the local administrator, who may use this logic to override package managers or the default installed configuration.

Configuration examples

The examples/configuration/tetragon.yaml file contains example entries showing the defaults as a guide to the administrator. Local overrides can be created by editing and copying this file into /etc/tetragon/tetragon.yaml, or by editing and copying “drop-ins” from the examples/configuration/tetragon.conf.d directory into the /etc/tetragon/tetragon.conf.d/ subdirectory. The latter is generally recommended.

Each filename maps to a one controlling setting and the content of the file to its corresponding value. This is the recommended way.

Changing configuration example:

/etc/tetragon/tetragon.conf.d/bpf-lib with a corresponding value of:
```
/var/lib/tetragon/
```
/etc/tetragon/tetragon.conf.d/log-format with a corresponding value of:
```
text
```
/etc/tetragon/tetragon.conf.d/export-filename with a corresponding value of:
```
/var/log/tetragon/tetragon.log
```

Note Defaults controlling settings can be restored by simply deleting /etc/tetragon/tetragon.yaml and all drop-ins under /etc/tetragon/tetragon.conf.d/

Restrict gRPC API access

The gRPC API supports unix sockets, it can be set using one of the following methods:

Use the --server-address flag:

--server-address unix:///var/run/tetragon/tetragon.sock

Or use the drop-in configuration file /etc/tetragon/tetragon.conf.d/server-address containing:
```
unix:///var/run/tetragon/tetragon.sock
```

Then to access the gRPC API with tetra client, set --server-address to point to the corresponding address:

sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock getevents

Note When reading events with the tetra client, if --server-address is not specified, it will try to detect if Tetragon daemon is running on the same host and use its server-address configuration.

Caution Ensure that you have enough privileges to open the gRPC unix socket since it is restricted to privileged users only.

Configure Tracing Policies location

Tetragon daemon automatically loads Tracing policies from the default /etc/tetragon/tetragon.tp.d/ directory. Tracing policies can be organized in directories such: /etc/tetragon/tetragon.tp.d/file-access, /etc/tetragon/tetragon.tp.d/network-access, etc.

The --tracing-policy-dir controlling setting can be used to change the default directory from where Tracing policies are loaded.

The --tracing-policy controlling setting can be used to specify the path of one tracing policy to load.

2 - Helm chart

This reference is generated from the Tetragon Helm chart values.

The Tetragon Helm chart source is available under github.io/cilium/tetragon/install/kubernetes/tetragon and is distributed from the Cilium helm charts repository helm.cilium.io.

To deploy Tetragon using this Helm chart you can run the following commands:

helm repo add cilium https://helm.cilium.io
helm repo update
helm install tetragon cilium/tetragon -n kube-system

To use the values available, with helm install or helm upgrade, use --set key=value.

Values

Key	Type	Default	Description
affinity	object	`{}`
crds.installMethod	string	`"operator"`	Method for installing CRDs. Supported values are: “operator”, “helm” and “none”. The “operator” method allows for fine-grained control over which CRDs are installed and by default doesn’t perform CRD downgrades. These can be configured in tetragonOperator section. The “helm” method always installs all CRDs for the chart version.
daemonSetAnnotations	object	`{}`
daemonSetLabelsOverride	object	`{}`
dnsPolicy	string	`"Default"`
enabled	bool	`true`	Global settings
export	object	`{"filenames":["tetragon.log"],"mode":"stdout","resources":{},"securityContext":{},"stdout":{"argsOverride":[],"commandOverride":[],"enabledArgs":true,"enabledCommand":true,"extraEnv":[],"extraVolumeMounts":[],"image":{"override":null,"repository":"quay.io/cilium/hubble-export-stdout","tag":"v1.0.4"}}}`	Tetragon event settings
exportDirectory	string	`"/var/run/cilium/tetragon"`
exportFileCreationInterval	string	`"120s"`
extraConfigmapMounts	list	`[]`
extraHostPathMounts	list	`[]`
extraVolumes	list	`[]`
hostNetwork	bool	`true`
imagePullPolicy	string	`"IfNotPresent"`
imagePullSecrets	list	`[]`
nodeSelector	object	`{}`
podAnnotations	object	`{}`
podLabels	object	`{}`
podLabelsOverride	object	`{}`
podSecurityContext	object	`{}`
priorityClassName	string	`""`	Tetragon agent settings
selectorLabelsOverride	object	`{}`
serviceAccount.annotations	object	`{}`
serviceAccount.create	bool	`true`
serviceAccount.name	string	`""`
serviceLabelsOverride	object	`{}`
tetragon.argsOverride	list	`[]`
tetragon.btf	string	`""`
tetragon.commandOverride	list	`[]`
tetragon.enableK8sAPI	bool	`true`
tetragon.enableMsgHandlingLatency	bool	`false`	Enable latency monitoring in message handling
tetragon.enablePolicyFilter	bool	`true`	Enable policy filter. This is required for K8s namespace and pod-label filtering.
tetragon.enablePolicyFilterDebug	bool	`false`	Enable policy filter debug messages.
tetragon.enableProcessCred	bool	`false`
tetragon.enableProcessNs	bool	`false`
tetragon.enabled	bool	`true`
tetragon.exportAllowList	string	`"{\"event_set\":[\"PROCESS_EXEC\", \"PROCESS_EXIT\", \"PROCESS_KPROBE\", \"PROCESS_UPROBE\", \"PROCESS_TRACEPOINT\"]}"`
tetragon.exportDenyList	string	`"{\"health_check\":true}\n{\"namespace\":[\"\", \"cilium\", \"kube-system\"]}"`
tetragon.exportFileCompress	bool	`false`
tetragon.exportFileMaxBackups	int	`5`
tetragon.exportFileMaxSizeMB	int	`10`
tetragon.exportFilePerm	string	`"600"`
tetragon.exportFilename	string	`"tetragon.log"`
tetragon.exportRateLimit	int	`-1`
tetragon.extraArgs	object	`{}`
tetragon.extraEnv	list	`[]`
tetragon.extraVolumeMounts	list	`[]`
tetragon.fieldFilters	string	`""`
tetragon.gops.address	string	`"localhost"`	The address at which to expose gops.
tetragon.gops.port	int	`8118`	The port at which to expose gops.
tetragon.grpc.address	string	`"localhost:54321"`	The address at which to expose gRPC. Examples: localhost:54321, unix:///var/run/tetragon/tetragon.sock
tetragon.grpc.enabled	bool	`true`	Whether to enable exposing Tetragon gRPC.
tetragon.hostProcPath	string	`"/proc"`	Location of the host proc filesystem in the runtime environment. If the runtime runs in the host, the path is /proc. Exceptions to this are environments like kind, where the runtime itself does not run on the host.
tetragon.image.override	string	`nil`
tetragon.image.repository	string	`"quay.io/cilium/tetragon"`
tetragon.image.tag	string	`"v1.1.0"`
tetragon.ociHookSetup	object	`{"enabled":false,"extraVolumeMounts":[],"failAllowNamespaces":"","installDir":"/opt/tetragon","interface":"oci-hooks","resources":{},"securityContext":{"privileged":true}}`	Configure tetragon’s init container for setting up tetragon-oci-hook on the host
tetragon.ociHookSetup.enabled	bool	`false`	enable init container to setup tetragon-oci-hook
tetragon.ociHookSetup.extraVolumeMounts	list	`[]`	Extra volume mounts to add to the oci-hook-setup init container
tetragon.ociHookSetup.failAllowNamespaces	string	`""`	Comma-separated list of namespaces to allow Pod creation for, in case tetragon-oci-hook fails to reach Tetragon agent. The namespace Tetragon is deployed in is always added as an exception and must not be added again.
tetragon.ociHookSetup.interface	string	`"oci-hooks"`	interface specifices how the hook is configured. There is only one avaialble value for now: “oci-hooks” (https://github.com/containers/common/blob/main/pkg/hooks/docs/oci-hooks.5.md).
tetragon.ociHookSetup.resources	object	`{}`	resources for the the oci-hook-setup init container
tetragon.ociHookSetup.securityContext	object	`{"privileged":true}`	Security context for oci-hook-setup init container
tetragon.processCacheSize	int	`65536`
tetragon.prometheus.address	string	`""`	The address at which to expose metrics. Set it to "" to expose on all available interfaces.
tetragon.prometheus.enabled	bool	`true`	Whether to enable exposing Tetragon metrics.
tetragon.prometheus.metricsLabelFilter	string	`"namespace,workload,pod,binary"`	Comma-separated list of enabled metrics labels. The configurable labels are: namespace, workload, pod, binary. Unkown labels will be ignored. Removing some labels from the list might help reduce the metrics cardinality if needed.
tetragon.prometheus.port	int	`2112`	The port at which to expose metrics.
tetragon.prometheus.serviceMonitor.enabled	bool	`false`	Whether to create a ‘ServiceMonitor’ resource targeting the tetragon pods.
tetragon.prometheus.serviceMonitor.labelsOverride	object	`{}`	The set of labels to place on the ‘ServiceMonitor’ resource.
tetragon.prometheus.serviceMonitor.scrapeInterval	string	`"10s"`	Interval at which metrics should be scraped. If not specified, Prometheus’ global scrape interval is used.
tetragon.redactionFilters	string	`""`
tetragon.resources	object	`{}`
tetragon.securityContext.privileged	bool	`true`
tetragonOperator	object	{"affinity":{},"annotations":{},"enabled":true,"extraLabels":{},"extraPodLabels":{},"extraVolumeMounts":[],"extraVolumes":[],"forceUpdateCRDs":false,"image":{"override":null,"pullPolicy":"IfNotPresent","repository":"quay.io/cilium/tetragon-operator","tag":"v1.1.0"},"nodeSelector":{},"podAnnotations":{},"podInfo":{"enabled":false},"podSecurityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}},"priorityClassName":"","prometheus":{"address":"","enabled":true,"port":2113,"serviceMonitor":{"enabled":false,"labelsOverride":{},"scrapeInterval":"10s"}},"resources":{"limits":{"cpu":"500m","memory":"128Mi"},"requests":{"cpu":"10m","memory":"64Mi"}},"securityContext":{},"serviceAccount":{"annotations":{},"create":true,"name":""},"skipCRDCreation":false,"strategy":{},"tolerations":[{"operator":"Exists"}],"tracingPolicy":{"enabled":true}}	Tetragon Operator settings
tetragonOperator.annotations	object	`{}`	Annotations for the Tetragon Operator Deployment.
tetragonOperator.enabled	bool	`true`	Enables the Tetragon Operator.
tetragonOperator.extraLabels	object	`{}`	Extra labels to be added on the Tetragon Operator Deployment.
tetragonOperator.extraPodLabels	object	`{}`	Extra labels to be added on the Tetragon Operator Deployment Pods.
tetragonOperator.extraVolumes	list	`[]`	Extra volumes for the Tetragon Operator Deployment.
tetragonOperator.image	object	`{"override":null,"pullPolicy":"IfNotPresent","repository":"quay.io/cilium/tetragon-operator","tag":"v1.1.0"}`	tetragon-operator image.
tetragonOperator.nodeSelector	object	`{}`	Steer the Tetragon Operator Deployment Pod placement via nodeSelector, tolerations and affinity rules.
tetragonOperator.podAnnotations	object	`{}`	Annotations for the Tetragon Operator Deployment Pods.
tetragonOperator.podInfo.enabled	bool	`false`	Enables the PodInfo CRD and the controller that reconciles PodInfo custom resources.
tetragonOperator.podSecurityContext	object	`{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}}`	securityContext for the Tetragon Operator Deployment Pod container.
tetragonOperator.priorityClassName	string	`""`	priorityClassName for the Tetragon Operator Deployment Pods.
tetragonOperator.prometheus	object	`{"address":"","enabled":true,"port":2113,"serviceMonitor":{"enabled":false,"labelsOverride":{},"scrapeInterval":"10s"}}`	Enables the Tetragon Operator metrics.
tetragonOperator.prometheus.address	string	`""`	The address at which to expose Tetragon Operator metrics. Set it to "" to expose on all available interfaces.
tetragonOperator.prometheus.port	int	`2113`	The port at which to expose metrics.
tetragonOperator.prometheus.serviceMonitor	object	`{"enabled":false,"labelsOverride":{},"scrapeInterval":"10s"}`	The labels to include with supporting metrics.
tetragonOperator.prometheus.serviceMonitor.enabled	bool	`false`	Whether to create a ‘ServiceMonitor’ resource targeting the tetragonOperator pods.
tetragonOperator.prometheus.serviceMonitor.labelsOverride	object	`{}`	The set of labels to place on the ‘ServiceMonitor’ resource.
tetragonOperator.prometheus.serviceMonitor.scrapeInterval	string	`"10s"`	Interval at which metrics should be scraped. If not specified, Prometheus’ global scrape interval is used.
tetragonOperator.resources	object	`{"limits":{"cpu":"500m","memory":"128Mi"},"requests":{"cpu":"10m","memory":"64Mi"}}`	resources for the Tetragon Operator Deployment Pod container.
tetragonOperator.securityContext	object	`{}`	securityContext for the Tetragon Operator Deployment Pods.
tetragonOperator.serviceAccount	object	`{"annotations":{},"create":true,"name":""}`	tetragon-operator service account.
tetragonOperator.skipCRDCreation	bool	`false`	DEPRECATED. This value will be removed in Tetragon v1.2 release. Use crds.installMethod instead. Skip CRD creation.
tetragonOperator.strategy	object	`{}`	resources for the Tetragon Operator Deployment update strategy
tetragonOperator.tracingPolicy.enabled	bool	`true`	Enables the TracingPolicy and TracingPolicyNamespaced CRD creation.
tolerations[0].operator	string	`"Exists"`
updateStrategy	object	`{}`

3 - gRPC API

This reference is generated from the protocol buffer specification and documents the gRPC API of Tetragon.

The Tetragon API is an independant Go module that can be found in the Tetragon repository under api. The version 1 of this API is defined in github.com/cilium/tetragon/api/v1/tetragon.

tetragon/capabilities.proto

CapabilitiesType

Name	Number	Description
CAP_CHOWN	0	In a system with the [_POSIX_CHOWN_RESTRICTED] option defined, this overrides the restriction of changing file ownership and group ownership.
DAC_OVERRIDE	1	Override all DAC access, including ACL execute access if [_POSIX_ACL] is defined. Excluding DAC access covered by CAP_LINUX_IMMUTABLE.
CAP_DAC_READ_SEARCH	2	Overrides all DAC restrictions regarding read and search on files and directories, including ACL restrictions if [_POSIX_ACL] is defined. Excluding DAC access covered by "$1"_LINUX_IMMUTABLE.
CAP_FOWNER	3	Overrides all restrictions about allowed operations on files, where file owner ID must be equal to the user ID, except where CAP_FSETID is applicable. It doesn't override MAC and DAC restrictions.
CAP_FSETID	4	Overrides the following restrictions that the effective user ID shall match the file owner ID when setting the S_ISUID and S_ISGID 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 S_ISGID bit on that file; that the S_ISUID and S_ISGID 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's capability bounding set to the current process' inheritable set Allow taking bits out of capability bounding set Allow modification of the securebits for a process
CAP_LINUX_IMMUTABLE	9	Allow modification of S_IMMUTABLE and S_APPEND file attributes
CAP_NET_BIND_SERVICE	10	Allows binding to ATM VCIs below 32
CAP_NET_BROADCAST	11	Allow broadcasting, listen to multicast
CAP_NET_ADMIN	12	Allow activation of ATM control sockets
CAP_NET_RAW	13	Allow binding to any address for transparent proxying (also via NET_ADMIN)
CAP_IPC_LOCK	14	Allow mlock and mlockall (which doesn't really have anything to do with IPC)
CAP_IPC_OWNER	15	Override IPC ownership checks
CAP_SYS_MODULE	16	Insert and remove kernel modules - modify kernel without limit
CAP_SYS_RAWIO	17	Allow sending USB messages to any device via /dev/bus/usb
CAP_SYS_CHROOT	18	Allow use of chroot()
CAP_SYS_PTRACE	19	Allow ptrace() of any process
CAP_SYS_PACCT	20	Allow configuration of process accounting
CAP_SYS_ADMIN	21	Allow everything under CAP_BPF and CAP_PERFMON for backward compatibility
CAP_SYS_BOOT	22	Allow use of reboot()
CAP_SYS_NICE	23	Allow setting cpu affinity on other processes
CAP_SYS_RESOURCE	24	Control memory reclaim behavior
CAP_SYS_TIME	25	Allow setting the real-time clock
CAP_SYS_TTY_CONFIG	26	Allow vhangup() of tty
CAP_MKNOD	27	Allow the privileged aspects of mknod()
CAP_LEASE	28	Allow taking of leases on files
CAP_AUDIT_WRITE	29	Allow writing the audit log via unicast netlink socket
CAP_AUDIT_CONTROL	30	Allow configuration of audit via unicast netlink socket
CAP_SETFCAP	31	Set or remove capabilities on files
CAP_MAC_OVERRIDE	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.
CAP_MAC_ADMIN	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's syslog (printk behaviour)
CAP_WAKE_ALARM	35	Allow triggering something that will wake the system
CAP_BLOCK_SUSPEND	36	Allow preventing system suspends
CAP_AUDIT_READ	37	Allow reading the audit log via multicast netlink socket
CAP_PERFMON	38	Allow system performance and observability privileged operations using perf_events, i915_perf and other kernel subsystems
CAP_BPF	39	CAP_BPF 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 bpf_spin_lock() helper CAP_PERFMON relaxes the verifier checks further: - BPF progs can use of pointer-to-integer conversions - speculation attack hardening measures are bypassed - bpf_probe_read to read arbitrary kernel memory is allowed - bpf_trace_printk to print kernel memory is allowed CAP_SYS_ADMIN is required to use bpf_probe_write_user. CAP_SYS_ADMIN is required to iterate system wide loaded programs, maps, links, BTFs and convert their IDs to file descriptors. CAP_PERFMON and CAP_BPF are required to load tracing programs. CAP_NET_ADMIN and CAP_BPF are required to load networking programs.
CAP_CHECKPOINT_RESTORE	40	Allow writing to ns_last_pid

ProcessPrivilegesChanged

Reasons of why the process privileges changed.

Name	Number	Description
PRIVILEGES_CHANGED_UNSET	0
PRIVILEGES_RAISED_EXEC_FILE_CAP	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` object.
PRIVILEGES_RAISED_EXEC_FILE_SETUID	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
PRIVILEGES_RAISED_EXEC_FILE_SETGID	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.

SecureBitsType

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-"fixup". 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()'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 set.
SecBitNoCapAmbientRaiseLocked	128	Make bit-6 SecBitNoCapAmbientRaise immutable

tetragon/tetragon.proto

BinaryProperties

Field	Type	Label	Description
setuid	google.protobuf.UInt32Value		If set then this is the set user ID used for execution
setgid	google.protobuf.UInt32Value		If set then this is the set group ID used for execution
privileges_changed	ProcessPrivilegesChanged	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 `process_credentials` or capabilities fields part of of the `process` object.
file	FileProperties		File properties in case the executed binary is: 1. An anonymous shared memory file https://man7.org/linux/man-pages/man7/shm_overview.7.html. 2. An anonymous file obtained with memfd API https://man7.org/linux/man-pages/man2/memfd_create.2.html. 3. Or it was deleted from the file system.

Capabilities

Field	Type	Label	Description
permitted	CapabilitiesType	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	CapabilitiesType	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	CapabilitiesType	repeated	Inheritable set indicates which capabilities will be inherited by the current process when running as a root user.

Container

Field	Type	Description
id	string	Identifier of the container.
name	string	Name of the container.
image	Image	Image of the container.
start_time	google.protobuf.Timestamp	Start time of the container.
pid	google.protobuf.UInt32Value	Process identifier in the container namespace.
maybe_exec_probe	bool	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, "/bin/ls" and "ls" are considered a match. 2. The arguments field exactly matches the rest of the exec command list.

CreateContainer

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	string		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	string		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	CreateContainer.AnnotationsEntry	repeated	annotations are the run-time annotations for the container see https://github.com/opencontainers/runtime-spec/blob/main/config.md#annotations
containerName	string		containerName is the name of the container

CreateContainer.AnnotationsEntry

Field	Type	Label	Description
key	string
value	string

FileProperties

Field	Type	Label	Description
inode	InodeProperties		Inode of the file
path	string		Path of the file

GetHealthStatusRequest

Field	Type	Label	Description
event_set	HealthStatusType	repeated

GetHealthStatusResponse

Field	Type	Label	Description
health_status	HealthStatus	repeated

HealthStatus

Field	Type	Label	Description
event	HealthStatusType
status	HealthStatusResult
details	string

Image

Field	Type	Label	Description
id	string		Identifier of the container image composed of the registry path and the sha256.
name	string		Name of the container image composed of the registry path and the tag.

InodeProperties

Field	Type	Label	Description
number	uint64		The inode number
links	google.protobuf.UInt32Value		The inode links on the file system. If zero means the file is only in memory

KernelModule

Field	Type	Label	Description
name	string		Kernel module name
signature_ok	google.protobuf.BoolValue		If true the module signature was verified successfully. Depends on kernels compiled with CONFIG_MODULE_SIG option, for details please read: https://www.kernel.org/doc/Documentation/admin-guide/module-signing.rst
tainted	TaintedBitsType	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

KprobeArgument

Field	Type	Description
string_arg	string
int_arg	int32
skb_arg	KprobeSkb
size_arg	uint64
bytes_arg	bytes
path_arg	KprobePath
file_arg	KprobeFile
truncated_bytes_arg	KprobeTruncatedBytes
sock_arg	KprobeSock
cred_arg	KprobeCred
long_arg	int64
bpf_attr_arg	KprobeBpfAttr
perf_event_arg	KprobePerfEvent
bpf_map_arg	KprobeBpfMap
uint_arg	uint32
user_namespace_arg	KprobeUserNamespace	Deprecated.
capability_arg	KprobeCapability
process_credentials_arg	ProcessCredentials
user_ns_arg	UserNamespace
module_arg	KernelModule
kernel_cap_t_arg	string	Capabilities in hexadecimal format.
cap_inheritable_arg	string	Capabilities inherited by a forked process in hexadecimal format.
cap_permitted_arg	string	Capabilities that are currently permitted in hexadecimal format.
cap_effective_arg	string	Capabilities that are actually used in hexadecimal format.
linux_binprm_arg	KprobeLinuxBinprm
net_dev_arg	KprobeNetDev
label	string

KprobeBpfAttr

Field	Type	Label	Description
ProgType	string
InsnCnt	uint32
ProgName	string

KprobeBpfMap

Field	Type	Label	Description
MapType	string
KeySize	uint32
ValueSize	uint32
MaxEntries	uint32
MapName	string

KprobeCapability

Field	Type	Label	Description
value	google.protobuf.Int32Value
name	string

KprobeCred

Field	Type	Label
permitted	CapabilitiesType	repeated
effective	CapabilitiesType	repeated
inheritable	CapabilitiesType	repeated

KprobeFile

Field	Type	Label	Description
mount	string
path	string
flags	string
permission	string

KprobeLinuxBinprm

Field	Type	Label	Description
path	string
flags	string
permission	string

KprobeNetDev

Field	Type	Label	Description
name	string

KprobePath

Field	Type	Label	Description
mount	string
path	string
flags	string
permission	string

KprobePerfEvent

Field	Type	Label	Description
KprobeFunc	string
Type	string
Config	uint64
ProbeOffset	uint64

KprobeSkb

Field	Type	Label	Description
hash	uint32
len	uint32
priority	uint32
mark	uint32
saddr	string
daddr	string
sport	uint32
dport	uint32
proto	uint32
sec_path_len	uint32
sec_path_olen	uint32
protocol	string
family	string

KprobeSock

Field	Type	Label	Description
family	string
type	string
protocol	string
mark	uint32
priority	uint32
saddr	string
daddr	string
sport	uint32
dport	uint32
cookie	uint64
state	string

KprobeTruncatedBytes

Field	Type	Label	Description
bytes_arg	bytes
orig_size	uint64

KprobeUserNamespace

Field	Type	Label	Description
level	google.protobuf.Int32Value
owner	google.protobuf.UInt32Value
group	google.protobuf.UInt32Value
ns	Namespace

Namespace

Field	Type	Label	Description
inum	uint32		Inode number of the namespace.
is_host	bool		Indicates if namespace belongs to host.

Namespaces

Field	Type	Description
uts	Namespace	Hostname and NIS domain name.
ipc	Namespace	System V IPC, POSIX message queues.
mnt	Namespace	Mount points.
pid	Namespace	Process IDs.
pid_for_children	Namespace	Process IDs for children processes.
net	Namespace	Network devices, stacks, ports, etc.
time	Namespace	Boot and monotonic clocks.
time_for_children	Namespace	Boot and monotonic clocks for children processes.
cgroup	Namespace	Cgroup root directory.
user	Namespace	User and group IDs.

Pod

Field	Type	Label	Description
namespace	string		Kubernetes namespace of the Pod.
name	string		Name of the Pod.
container	Container		Container of the Pod from which the process that triggered the event originates.
pod_labels	Pod.PodLabelsEntry	repeated	Contains all the labels of the pod.
workload	string		Kubernetes workload of the Pod.
workload_kind	string		Kubernetes workload kind (e.g. "Deployment", "DaemonSet") of the Pod.

Pod.PodLabelsEntry

Field	Type	Label	Description
key	string
value	string

Process

Field	Type	Description
exec_id	string	Exec ID uniquely identifies the process over time across all the nodes in the cluster.
pid	google.protobuf.UInt32Value	Process identifier from host PID namespace.
uid	google.protobuf.UInt32Value	User identifier associated with the process.
cwd	string	Current working directory of the process.
binary	string	Absolute path of the executed binary.
arguments	string	Arguments passed to the binary at execution.
flags	string	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'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 debugging. 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 '/' 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'd process.
start_time	google.protobuf.Timestamp	Start time of the execution.
auid	google.protobuf.UInt32Value	Audit user ID, this ID is assigned to a user upon login and is inherited by every process even when the user's identity changes. For example, by switching user accounts with su - john.
pod	Pod	Information about the the Kubernetes Pod where the event originated.
docker	string	The 15 first digits of the container ID.
parent_exec_id	string	Exec ID of the parent process.
refcnt	uint32	Reference counter from the Tetragon process cache.
cap	Capabilities	Set of capabilities that define the permissions the process can execute with.
ns	Namespaces	Linux namespaces of the process, disabled by default, can be enabled by the `--enable-process-ns` flag.
tid	google.protobuf.UInt32Value	Thread ID, note that for the thread group leader, tid is equal to pid.
process_credentials	ProcessCredentials	Process credentials
binary_properties	BinaryProperties	Executed binary properties. This field is only available on ProcessExec events.
user	UserRecord	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 "unix". 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 resolution. |

ProcessCredentials

Field	Type	Label	Description
uid	google.protobuf.UInt32Value		The real user ID
gid	google.protobuf.UInt32Value		The real group ID
euid	google.protobuf.UInt32Value		The effective user ID
egid	google.protobuf.UInt32Value		The effective group ID
suid	google.protobuf.UInt32Value		The saved user ID
sgid	google.protobuf.UInt32Value		The saved group ID
fsuid	google.protobuf.UInt32Value		the filesystem user ID
fsgid	google.protobuf.UInt32Value		The filesystem group ID
securebits	SecureBitsType	repeated	Secure management flags
caps	Capabilities		Set of capabilities that define the permissions the process can execute with.
user_ns	UserNamespace		User namespace where the UIDs, GIDs and capabilities are relative to.

ProcessExec

Field	Type	Label	Description
process	Process		Process that triggered the exec.
parent	Process		Immediate parent of the process.
ancestors	Process	repeated	Ancestors of the process beyond the immediate parent.

ProcessExit

Field	Type	Description
process	Process	Process that triggered the exit.
parent	Process	Immediate parent of the process.
signal	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	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	Date and time of the event.

ProcessKprobe

Field	Type	Label	Description
process	Process		Process that triggered the kprobe.
parent	Process		Immediate parent of the process.
function_name	string		Symbol on which the kprobe was attached.
args	KprobeArgument	repeated	Arguments definition of the observed kprobe.
return	KprobeArgument		Return value definition of the observed kprobe.
action	KprobeAction		Action performed when the kprobe matched.
kernel_stack_trace	StackTraceEntry	repeated	Kernel stack trace to the call.
policy_name	string		Name of the Tracing Policy that created that kprobe.
return_action	KprobeAction		Action performed when the return kprobe executed.
message	string		Short message of the Tracing Policy to inform users what is going on.
tags	string	repeated	Tags of the Tracing Policy to categorize the event.
user_stack_trace	StackTraceEntry	repeated	User-mode stack trace to the call.

ProcessLoader

loader sensor event triggered for loaded binary/library

Field	Type	Label	Description
process	Process
path	string
buildid	bytes

ProcessTracepoint

Field	Type	Label	Description
process	Process		Process that triggered the tracepoint.
parent	Process		Immediate parent of the process.
subsys	string		Subsystem of the tracepoint.
event	string		Event of the subsystem.
args	KprobeArgument	repeated	Arguments definition of the observed tracepoint. TODO: once we implement all we want, rename KprobeArgument to GenericArgument
policy_name	string		Name of the policy that created that tracepoint.
action	KprobeAction		Action performed when the tracepoint matched.
message	string		Short message of the Tracing Policy to inform users what is going on.
tags	string	repeated	Tags of the Tracing Policy to categorize the event.

ProcessUprobe

Field	Type	Label	Description
process	Process
parent	Process
path	string
symbol	string
policy_name	string		Name of the policy that created that uprobe.
message	string		Short message of the Tracing Policy to inform users what is going on.
args	KprobeArgument	repeated	Arguments definition of the observed uprobe.
tags	string	repeated	Tags of the Tracing Policy to categorize the event.

RuntimeHookRequest

RuntimeHookRequest synchronously propagates information to the agent about run-time state.

Field	Type	Label	Description
createContainer	CreateContainer

RuntimeHookResponse

StackTraceEntry

Field	Type	Description
address	uint64	linear address of the function in kernel or user space.
offset	uint64	offset is the offset into the native instructions for the function.
symbol	string	symbol is the symbol name of the function.
module	string	module path for user space addresses.

Test

Field	Type	Label	Description
arg0	uint64
arg1	uint64
arg2	uint64
arg3	uint64

UserNamespace

Field	Type	Description
level	google.protobuf.Int32Value	Nested level of the user namespace. Init or host user namespace is at level 0.
uid	google.protobuf.UInt32Value	The owner user ID of the namespace
gid	google.protobuf.UInt32Value	The owner group ID of the namepace.
ns	Namespace	The user namespace details that include the inode number of the namespace.

UserRecord

User records

Field	Type	Label	Description
name	string		The UNIX username for this record. Corresponds to `pw_name` field of struct passwd and the `sp_namp` field of struct spwd.

HealthStatusResult

Name	Number	Description
HEALTH_STATUS_UNDEF	0
HEALTH_STATUS_RUNNING	1
HEALTH_STATUS_STOPPED	2
HEALTH_STATUS_ERROR	3

HealthStatusType

Name	Number	Description
HEALTH_STATUS_TYPE_UNDEF	0
HEALTH_STATUS_TYPE_STATUS	1

KprobeAction

Name	Number	Description
KPROBE_ACTION_UNKNOWN	0	Unknown action
KPROBE_ACTION_POST	1	Post action creates an event (default action).
KPROBE_ACTION_FOLLOWFD	2	Post action creates a mapping between file descriptors and file names.
KPROBE_ACTION_SIGKILL	3	Sigkill action synchronously terminates the process.
KPROBE_ACTION_UNFOLLOWFD	4	Post action removes a mapping between file descriptors and file names.
KPROBE_ACTION_OVERRIDE	5	Override action modifies the return value of the call.
KPROBE_ACTION_COPYFD	6	Post action dupplicates a mapping between file descriptors and file names.
KPROBE_ACTION_GETURL	7	GetURL action issue an HTTP Get request against an URL from userspace.
KPROBE_ACTION_DNSLOOKUP	8	GetURL action issue a DNS lookup against an URL from userspace.
KPROBE_ACTION_NOPOST	9	NoPost action suppresses the transmission of the event to userspace.
KPROBE_ACTION_SIGNAL	10	Signal action sends specified signal to the process.
KPROBE_ACTION_TRACKSOCK	11	TrackSock action tracks socket.
KPROBE_ACTION_UNTRACKSOCK	12	UntrackSock action un-tracks socket.
KPROBE_ACTION_NOTIFYENFORCER	13	NotifyEnforcer action notifies killer sensor.

TaintedBitsType

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
TAINT_PROPRIETARY_MODULE	1	A proprietary module was loaded.
TAINT_FORCED_MODULE	2	A module was force loaded.
TAINT_FORCED_UNLOAD_MODULE	4	A module was force unloaded.
TAINT_STAGED_MODULE	1024	A staging driver was loaded.
TAINT_OUT_OF_TREE_MODULE	4096	An out of tree module was loaded.
TAINT_UNSIGNED_MODULE	8192	An unsigned module was loaded. Supported only on kernels built with CONFIG_MODULE_SIG option.
TAINT_KERNEL_LIVE_PATCH_MODULE	32768	The kernel has been live patched.
TAINT_TEST_MODULE	262144	Loading a test module.

tetragon/events.proto

AggregationInfo

AggregationInfo contains information about aggregation results.

Field	Type	Label	Description
count	uint64		Total count of events in this aggregation time window.

AggregationOptions

AggregationOptions defines configuration options for aggregating events.

Field	Type	Label	Description
window_size	google.protobuf.Duration		Aggregation window size. Defaults to 15 seconds if this field is not set.
channel_buffer_size	uint64		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.

CapFilter

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	Description
permitted	CapFilterSet	Filter over the set of permitted capabilities.
effective	CapFilterSet	Filter over the set of effective capabilities.
inheritable	CapFilterSet	Filter over the set of inheritable capabilities.

CapFilterSet

Capability set to filter over. NOTE: you may specify only ONE set here.

Field	Type	Label	Description
any	CapabilitiesType	repeated	Match if the capability set contains any of the capabilities defined in this filter.
all	CapabilitiesType	repeated	Match if the capability set contains all of the capabilities defined in this filter.
exactly	CapabilitiesType	repeated	Match if the capability set exactly matches all of the capabilities defined in this filter.
none	CapabilitiesType	repeated	Match if the capability set contains none of the capabilities defined in this filter.

FieldFilter

Field	Type	Label	Description
event_set	EventType	repeated	Event types to filter or undefined to filter over all event types.
fields	google.protobuf.FieldMask		Fields to include or exclude.
action	FieldFilterAction		Whether to include or exclude fields.
invert_event_set	google.protobuf.BoolValue		Whether or not the event set filter should be inverted.

Filter

Field	Type	Label	Description
binary_regex	string	repeated
namespace	string	repeated
health_check	google.protobuf.BoolValue
pid	uint32	repeated
pid_set	uint32	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	EventType	repeated
pod_regex	string	repeated	Filter by process.pod.name field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax
arguments_regex	string	repeated	Filter by process.arguments field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax
labels	string	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	string	repeated	Filter events by tracing policy names
capabilities	CapFilter		Filter events by Linux process capability

GetEventsRequest

Field	Type	Label	Description
allow_list	Filter	repeated	allow_list 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.
deny_list	Filter	repeated	deny_list 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 allow_list and deny_list are specified, the results contain the set difference allow_list - deny_list.
aggregation_options	AggregationOptions		aggregation_options configures aggregation options for this request. If this field is not set, responses will not be aggregated. Note that currently only process_accept and process_connect events are aggregated. Other events remain unaggregated.
field_filters	FieldFilter	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.

GetEventsResponse

Field	Type	Description
process_exec	ProcessExec	ProcessExec event includes information about the execution of binaries and other related process metadata.
process_exit	ProcessExit	ProcessExit event indicates how and when a process terminates.
process_kprobe	ProcessKprobe	ProcessKprobe event contains information about the pre-defined functions and the process that invoked them.
process_tracepoint	ProcessTracepoint	ProcessTracepoint contains information about the pre-defined tracepoint and the process that invoked them.
process_loader	ProcessLoader
process_uprobe	ProcessUprobe
process_throttle	ProcessThrottle
test	Test
rate_limit_info	RateLimitInfo
node_name	string	Name of the node where this event was observed.
time	google.protobuf.Timestamp	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.
aggregation_info	AggregationInfo	aggregation_info contains information about aggregation results. This field is set only for aggregated responses.

ProcessThrottle

Field	Type	Label	Description
type	ThrottleType		Throttle type
cgroup	string		Cgroup name

RateLimitInfo

Field	Type	Label	Description
number_of_dropped_process_events	uint64

RedactionFilter

Field	Type	Label	Description
match	Filter	repeated	Deprecated. Deprecated, do not use.
redact	string	repeated	RE2 regular expressions to use for redaction. Strings inside capture groups are redacted.
binary_regex	string	repeated	RE2 regular expression to match binary name. If supplied, redactions will only be applied to matching processes.

EventType

Represents the type of a Tetragon event.

NOTE: EventType constants must be in sync with the numbers used in the GetEventsResponse event oneof.

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
RATE_LIMIT_INFO	40001

FieldFilterAction

Determines the behavior of a field filter

Name	Number	Description
INCLUDE	0
EXCLUDE	1

ThrottleType

Name	Number	Description
THROTTLE_UNKNOWN	0
THROTTLE_START	1
THROTTLE_STOP	2

tetragon/stack.proto

StackAddress

Field	Type	Label	Description
address	uint64
symbol	string

StackTrace

Field	Type	Label	Description
addresses	StackAddress	repeated

StackTraceLabel

Field	Type	Label	Description
key	string
count	uint64

StackTraceNode

Field	Type	Label
address	StackAddress
count	uint64
labels	StackTraceLabel	repeated
children	StackTraceNode	repeated

tetragon/sensors.proto

AddTracingPolicyRequest

Field	Type	Label	Description
yaml	string

AddTracingPolicyResponse

DeleteTracingPolicyRequest

Field	Type	Label	Description
name	string

DeleteTracingPolicyResponse

DisableSensorRequest

Field	Type	Label	Description
name	string

DisableSensorResponse

DisableTracingPolicyRequest

Field	Type	Label	Description
name	string

DisableTracingPolicyResponse

EnableSensorRequest

Field	Type	Label	Description
name	string

EnableSensorResponse

EnableTracingPolicyRequest

Field	Type	Label	Description
name	string

EnableTracingPolicyResponse

GetStackTraceTreeRequest

Field	Type	Label	Description
name	string

GetStackTraceTreeResponse

Field	Type	Label	Description
root	StackTraceNode

GetVersionRequest

GetVersionResponse

Field	Type	Label	Description
version	string

ListSensorsRequest

ListSensorsResponse

Field	Type	Label	Description
sensors	SensorStatus	repeated

ListTracingPoliciesRequest

ListTracingPoliciesResponse

Field	Type	Label	Description
policies	TracingPolicyStatus	repeated

RemoveSensorRequest

Field	Type	Label	Description
name	string

RemoveSensorResponse

SensorStatus

Field	Type	Description
name	string	name is the name of the sensor
enabled	bool	enabled marks whether the sensor is enabled
collection	string	collection is the collection the sensor belongs to (typically a tracing policy)

TracingPolicyStatus

Field	Type	Label	Description
id	uint64		id is the id of the policy
name	string		name is the name of the policy
namespace	string		namespace is the namespace of the policy (or empty of the policy is global)
info	string		info is additional information about the policy
sensors	string	repeated	sensors loaded in the scope of this policy
enabled	bool		Deprecated. indicating if the policy is enabled. Deprecated: use 'state' instead.
filter_id	uint64		filter ID of the policy used for k8s filtering
error	string		potential error of the policy
state	TracingPolicyState		current state of the tracing policy

TracingPolicyState

Name	Number	Description
TP_STATE_UNKNOWN	0	unknown state
TP_STATE_ENABLED	1	loaded and enabled
TP_STATE_DISABLED	2	loaded but disabled
TP_STATE_LOAD_ERROR	3	failed to load
TP_STATE_ERROR	4	failed during lifetime

FineGuidanceSensors

Method Name	Request Type	Response Type
GetEvents	GetEventsRequest	GetEventsResponse stream
GetHealth	GetHealthStatusRequest	GetHealthStatusResponse
AddTracingPolicy	AddTracingPolicyRequest	AddTracingPolicyResponse
DeleteTracingPolicy	DeleteTracingPolicyRequest	DeleteTracingPolicyResponse
RemoveSensor	RemoveSensorRequest	RemoveSensorResponse
ListTracingPolicies	ListTracingPoliciesRequest	ListTracingPoliciesResponse
EnableTracingPolicy	EnableTracingPolicyRequest	EnableTracingPolicyResponse
DisableTracingPolicy	DisableTracingPolicyRequest	DisableTracingPolicyResponse
ListSensors	ListSensorsRequest	ListSensorsResponse
EnableSensor	EnableSensorRequest	EnableSensorResponse
DisableSensor	DisableSensorRequest	DisableSensorResponse
GetStackTraceTree	GetStackTraceTreeRequest	GetStackTraceTreeResponse
GetVersion	GetVersionRequest	GetVersionResponse
RuntimeHook	RuntimeHookRequest	RuntimeHookResponse

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
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)
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
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
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)
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
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)
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
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)

4 - Metrics

This reference is autogenerated from the Tetragon Prometheus metrics registry.

Tetragon Health Metrics

`tetragon_build_info`

Build information about tetragon

label	values
`commit`	`931b70f2c9878ba985ba6b589827bea17da6ec33`
`go_version`	`go1.22.0`
`modified`	`false`
`time`	`2022-05-13T15:54:45Z`

`tetragon_data_event_size`

The size of received data events.

label	values
`op`	`bad, ok`

`tetragon_data_events_total`

The number of data events by type. For internal use only.

label	values
`event`	`Added, Appended, Bad, Matched, NotMatched, Received`

`tetragon_errors_total`

The total number of Tetragon errors. For internal use only.

label	values
`type`	`event_finalize_process_info_failed, event_missing_process_info, handler_error, process_cache_evicted, process_cache_miss_on_get, process_cache_miss_on_remove, process_pid_tid_mismatch`

`tetragon_event_cache_accesses_total`

The total number of Tetragon event cache accesses. For internal use only.

`tetragon_event_cache_entries`

The number of entries in the event cache.

`tetragon_event_cache_errors_total`

The total of errors encountered while fetching process exec information from the cache.

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`

`tetragon_event_cache_parent_info_errors_total`

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`

`tetragon_event_cache_pod_info_errors_total`

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`

`tetragon_event_cache_process_info_errors_total`

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`

`tetragon_event_cache_retries_total`

The total number of retries for event caching per entry type.

label	values
`entry_type`	`parent_info, pod_info, process_info`

`tetragon_events_exported_bytes_total`

Number of bytes exported for events

`tetragon_events_exported_total`

Total number of events exported

`tetragon_events_last_exported_timestamp`

Timestamp of the most recent event to be exported

`tetragon_flags_total`

The total number of Tetragon flags. For internal use only.

label	values
`type`	`auid, clone, errorArgs, errorCWD, errorCgroupID, errorCgroupKn, errorCgroupName, errorCgroupSubsys, errorCgroupSubsysCgrp, errorCgroups, errorFilename, errorPathResolutionCwd, execve, execveat, miss, nocwd, procFS, rootcwd, taskWalk, truncArgs, truncFilename`

`tetragon_generic_kprobe_merge_errors_total`

The total number of failed attempts to merge a kprobe and kretprobe event.

label	values
`curr_fn`	`example_kprobe`
`curr_type`	`enter, exit`
`prev_fn`	`example_kprobe`
`prev_type`	`enter, exit`

`tetragon_generic_kprobe_merge_ok_total`

The total number of successful attempts to merge a kprobe and kretprobe event.

`tetragon_generic_kprobe_merge_pushed_total`

The total number of pushed events for later merge.

`tetragon_handler_errors_total`

The total number of event handler errors. For internal use only.

label	values
`error_type`	`event_handler_failed, unknown_opcode`
`opcode`	`0, 11, 13, 14, 15, 23, 24, 25, 26, 5, 7`

`tetragon_handling_latency`

The latency of handling messages in us.

label	values
`op`	`11, 13, 14, 15, 23, 24, 25, 26, 5, 7`

`tetragon_map_capacity`

Capacity of a BPF map. Expected to be constant.

label	values
`map`	`execve_map, tg_execve_joined_info_map`

`tetragon_map_entries`

The total number of in-use entries per map.

label	values
`map`	`execve_map, tg_execve_joined_info_map`

`tetragon_map_errors_total`

The number of errors per map.

label	values
`map`	`execve_map, tg_execve_joined_info_map`

`tetragon_missed_events_total`

The total number of Tetragon events per type that are failed to sent from the kernel.

label	values
`msg_op`	`11, 13, 14, 15, 23, 24, 25, 26, 5, 7`

`tetragon_msg_op_total`

The total number of times we encounter a given message opcode. For internal use only.

label	values
`msg_op`	`11, 13, 14, 15, 23, 24, 25, 26, 5, 7`

`tetragon_notify_overflowed_events_total`

The total number of events dropped because listener buffer was full

`tetragon_policyfilter_hook_container_name_missing_total`

The total number of operations when the container name was missing in the OCI hook

`tetragon_policyfilter_metrics_total`

Policy filter metrics. For internal use only.

label	values
`error`	`generic-error, pod-namespace-conflict`
`op`	`add, add-container, delete, update`
`subsys`	`pod-handlers, rthooks`

`tetragon_process_cache_capacity`

The capacity of the process cache. Expected to be constant.

`tetragon_process_cache_size`

The size of the process cache

`tetragon_process_loader_stats`

Process Loader event statistics. For internal use only.

label	values
`count`	`LoaderReceived, LoaderResolvedImm, LoaderResolvedRetry`

`tetragon_ratelimit_dropped_total`

The total number of rate limit Tetragon drops

`tetragon_ringbuf_perf_event_errors_total`

The total number of errors when reading the Tetragon ringbuf.

`tetragon_ringbuf_perf_event_lost_total`

The total number of Tetragon ringbuf perf events lost.

`tetragon_ringbuf_perf_event_received_total`

The total number of Tetragon ringbuf perf events received.

`tetragon_ringbuf_queue_lost_total`

The total number of Tetragon events ring buffer queue lost.

`tetragon_ringbuf_queue_received_total`

The total number of Tetragon events ring buffer queue received.

`tetragon_tracingpolicy_loaded`

The number of loaded tracing policy by state.

label	values
`state`	`disabled, enabled, error, load_error`

`tetragon_watcher_errors_total`

The total number of errors for a given watcher type.

label	values
`error`	`failed_to_get_pod`
`watcher`	`k8s`

`tetragon_watcher_events_total`

The total number of events for a given watcher type.

label	values
`watcher`	`k8s`

Tetragon Resources Metrics

`go_gc_duration_seconds`

A summary of the pause duration of garbage collection cycles.

`go_goroutines`

Number of goroutines that currently exist.

`go_info`

Information about the Go environment.

label	values
`version`	`go1.22.0`

`go_memstats_alloc_bytes`

Number of bytes allocated and still in use.

`go_memstats_alloc_bytes_total`

Total number of bytes allocated, even if freed.

`go_memstats_buck_hash_sys_bytes`

Number of bytes used by the profiling bucket hash table.

`go_memstats_frees_total`

Total number of frees.

`go_memstats_gc_sys_bytes`

Number of bytes used for garbage collection system metadata.

`go_memstats_heap_alloc_bytes`

Number of heap bytes allocated and still in use.

`go_memstats_heap_idle_bytes`

Number of heap bytes waiting to be used.

`go_memstats_heap_inuse_bytes`

Number of heap bytes that are in use.

`go_memstats_heap_objects`

Number of allocated objects.

`go_memstats_heap_released_bytes`

Number of heap bytes released to OS.

`go_memstats_heap_sys_bytes`

Number of heap bytes obtained from system.

`go_memstats_last_gc_time_seconds`

Number of seconds since 1970 of last garbage collection.

`go_memstats_lookups_total`

Total number of pointer lookups.

`go_memstats_mallocs_total`

Total number of mallocs.

`go_memstats_mcache_inuse_bytes`

Number of bytes in use by mcache structures.

`go_memstats_mcache_sys_bytes`

Number of bytes used for mcache structures obtained from system.

`go_memstats_mspan_inuse_bytes`

Number of bytes in use by mspan structures.

`go_memstats_mspan_sys_bytes`

Number of bytes used for mspan structures obtained from system.

`go_memstats_next_gc_bytes`

Number of heap bytes when next garbage collection will take place.

`go_memstats_other_sys_bytes`

Number of bytes used for other system allocations.

`go_memstats_stack_inuse_bytes`

Number of bytes in use by the stack allocator.

`go_memstats_stack_sys_bytes`

Number of bytes obtained from system for stack allocator.

`go_memstats_sys_bytes`

Number of bytes obtained from system.

`go_threads`

Number of OS threads created.

`process_cpu_seconds_total`

Total user and system CPU time spent in seconds.

`process_max_fds`

Maximum number of open file descriptors.

`process_open_fds`

Number of open file descriptors.

`process_resident_memory_bytes`

Resident memory size in bytes.

`process_start_time_seconds`

Start time of the process since unix epoch in seconds.

`process_virtual_memory_bytes`

Virtual memory size in bytes.

`process_virtual_memory_max_bytes`

Maximum amount of virtual memory available in bytes.

Tetragon Events Metrics

`tetragon_events_total`

The total number of Tetragon events

label	values
`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`
`workload`	`example-workload`

`tetragon_policy_events_total`

Policy events calls observed.

label	values
`binary`	`example-binary`
`hook`	`example_kprobe`
`namespace`	`example-namespace`
`pod`	`example-pod`
`policy`	`example-tracingpolicy`
`workload`	`example-workload`

`tetragon_syscalls_total`

System calls observed.

label	values
`binary`	`example-binary`
`namespace`	`example-namespace`
`pod`	`example-pod`
`syscall`	`example_syscall`
`workload`	`example-workload`