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

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.

FlagUsageDefault Value
--bpf-libLocation of Tetragon libs (btf and bpf files)/var/lib/tetragon/
--btfLocation of btf
--config-dirConfiguration directory that contains a file for each option
--cpuprofileStore CPU profile into provided file
--data-cache-sizeSize of the data events cache1024
--debugEnable debug messages. Equivalent to '--log-level=debug'false
--disable-kprobe-multiAllow to disable kprobe multi interfacefalse
--enable-export-aggregationEnable JSON export aggregationfalse
--enable-k8s-apiAccess Kubernetes API to associate Tetragon events with Kubernetes podsfalse
--enable-msg-handling-latencyEnable metrics for message handling latencyfalse
--enable-pid-set-filterEnable pidSet export filters. Not recommended for production usefalse
--enable-pod-infoEnable PodInfo custom resourcefalse
--enable-policy-filterEnable policy filter code (beta)false
--enable-policy-filter-debugEnable policy filter debug messagesfalse
--enable-process-ancestorsInclude ancestors in process exec eventstrue
--enable-process-credEnable process_cred eventsfalse
--enable-process-nsEnable namespace information in process_exec and process_kprobe eventsfalse
--enable-tracing-policy-crdEnable TracingPolicy and TracingPolicyNamespaced custom resourcestrue
--event-queue-sizeSet the size of the internal event queue.10000
--export-aggregation-buffer-sizeAggregator channel buffer size10000
--export-aggregation-window-sizeJSON export aggregation time window15s
--export-allowlistJSON export allowlist
--export-denylistJSON export denylist
--export-file-compressCompress rotated JSON export filesfalse
--export-file-max-backupsNumber of rotated JSON export files to retain5
--export-file-max-size-mbSize in MB for rotating JSON export files10
--export-file-permAccess permissions on JSON export files600
--export-file-rotation-intervalInterval at which to rotate JSON export files in addition to rotating them by size0s
--export-filenameFilename for JSON export. Disabled by default
--export-rate-limitRate limit (per minute) for event export. Set to -1 to disable-1
--expose-kernel-addressesExpose real kernel addresses in events stack tracesfalse
--field-filtersField filters for event exports
--force-large-progsForce loading large programs, even in kernels with < 5.3 versionsfalse
--force-small-progsForce loading small programs, even in kernels with >= 5.3 versionsfalse
--generate-docsGenerate documentation in YAML format to stdoutfalse
--gops-addressgops server address (e.g. 'localhost:8118'). Disabled by default
--helphelp for tetragonfalse
--k8s-kubeconfig-pathAbsolute path of the kubernetes kubeconfig file
--kernelKernel version
--kmodsList of kernel modules to load symbols from[]
--log-formatSet log formattext
--log-levelSet log levelinfo
--memprofileStore MEM profile into provided file
--metrics-label-filterComma-separated list of enabled metric labels. (e.g. "namespace,workload,pod,binary") By default all labels are enabled.
--metrics-serverMetrics server address (e.g. ':2112'). Disabled by default
--netns-dirNetwork namespace dir/var/run/docker/netns/
--pprof-addrProfile via pprof http
--process-cache-sizeSize of the process cache65536
--procfsLocation of procfs to consume existing PIDs/proc/
--rb-queue-sizeSet size of channel between ring buffer and sensor go routines (default 65k, allows K/M/G suffix)65535
--rb-sizeSet perf ring buffer size for single cpu (default 65k, allows K/M/G suffix)0
--rb-size-totalSet perf ring buffer size in total for all cpus (default 65k per cpu, allows K/M/G suffix)0
--release-pinned-bpfRelease all pinned BPF programs and maps in Tetragon BPF directory. Enabled by default. Set to false to disabletrue
--server-addressgRPC server address (e.g. 'localhost:54321' or 'unix:///var/run/tetragon/tetragon.sock'localhost:54321
--tracing-policyTracing policy file to load at startup
--tracing-policy-dirDirectory from where to load Tracing Policies/etc/tetragon/tetragon.tp.d
--verboseset verbosity level for eBPF verifier dumps. Pass 0 for silent, 1 for truncated logs, 2 for a full dump0

Configuration precedence

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

  1. 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/*
  2. From the configuration file /etc/tetragon/tetragon.yaml if available, overriding previous settings.

  3. From the drop-in configuration snippets inside /etc/tetragon/tetragon.conf.d/*, similarly overriding previous settings.

  4. 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:

  1. Drop-in directory pointed by --config-dir.

  2. Drop-in directory /etc/tetragon/tetragon.conf.d/*.

  3. Configuration file /etc/tetragon/tetragon.yaml.

  4. Drop-in directories:

    • /usr/local/lib/tetragon/tetragon.conf.d/*
    • /usr/lib/tetragon/tetragon.conf.d/*

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
    

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

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

KeyTypeDefaultDescription
affinityobject{}
daemonSetAnnotationsobject{}
daemonSetLabelsOverrideobject{}
dnsPolicystring"Default"
enabledbooltrueGlobal settings
exportobject{"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
exportDirectorystring"/var/run/cilium/tetragon"
exportFileCreationIntervalstring"120s"
extraConfigmapMountslist[]
extraHostPathMountslist[]
extraVolumeslist[]
hostNetworkbooltrue
imagePullPolicystring"IfNotPresent"
imagePullSecretslist[]
nodeSelectorobject{}
podAnnotationsobject{}
podLabelsobject{}
podLabelsOverrideobject{}
podSecurityContextobject{}
priorityClassNamestring""Tetragon agent settings
selectorLabelsOverrideobject{}
serviceAccount.annotationsobject{}
serviceAccount.createbooltrue
serviceAccount.namestring""
serviceLabelsOverrideobject{}
tetragon.argsOverridelist[]
tetragon.btfstring""
tetragon.commandOverridelist[]
tetragon.enableK8sAPIbooltrue
tetragon.enableMsgHandlingLatencyboolfalseEnable latency monitoring in message handling
tetragon.enablePolicyFilterbooltrueEnable policy filter. This is required for K8s namespace and pod-label filtering.
tetragon.enablePolicyFilterDebugboolfalseEnable policy filter debug messages.
tetragon.enableProcessCredboolfalse
tetragon.enableProcessNsboolfalse
tetragon.enabledbooltrue
tetragon.exportAllowListstring"{\"event_set\":[\"PROCESS_EXEC\", \"PROCESS_EXIT\", \"PROCESS_KPROBE\", \"PROCESS_UPROBE\", \"PROCESS_TRACEPOINT\"]}"
tetragon.exportDenyListstring"{\"health_check\":true}\n{\"namespace\":[\"\", \"cilium\", \"kube-system\"]}"
tetragon.exportFileCompressboolfalse
tetragon.exportFileMaxBackupsint5
tetragon.exportFileMaxSizeMBint10
tetragon.exportFilePermstring"600"
tetragon.exportFilenamestring"tetragon.log"
tetragon.exportRateLimitint-1
tetragon.extraArgsobject{}
tetragon.extraEnvlist[]
tetragon.extraVolumeMountslist[]
tetragon.fieldFiltersstring"{}"
tetragon.gops.addressstring"localhost"The address at which to expose gops.
tetragon.gops.portint8118The port at which to expose gops.
tetragon.grpc.addressstring"localhost:54321"The address at which to expose gRPC. Examples: localhost:54321, unix:///var/run/tetragon/tetragon.sock
tetragon.grpc.enabledbooltrueWhether to enable exposing Tetragon gRPC.
tetragon.hostProcPathstring"/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.overridestringnil
tetragon.image.repositorystring"quay.io/cilium/tetragon"
tetragon.image.tagstring"v1.0.2"
tetragon.ociHookSetupobject{"enabled":false,"extraVolumeMounts":[],"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.enabledboolfalseenable init container to setup tetragon-oci-hook
tetragon.ociHookSetup.extraVolumeMountslist[]Extra volume mounts to add to the oci-hook-setup init container
tetragon.ociHookSetup.interfacestring"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.resourcesobject{}resources for the the oci-hook-setup init container
tetragon.ociHookSetup.securityContextobject{"privileged":true}Security context for oci-hook-setup init container
tetragon.processCacheSizeint65536
tetragon.prometheus.addressstring""The address at which to expose metrics. Set it to "" to expose on all available interfaces.
tetragon.prometheus.enabledbooltrueWhether to enable exposing Tetragon metrics.
tetragon.prometheus.metricsLabelFilterstring"namespace,workload,pod,binary"The labels to include with supporting metrics. The possible values are “namespace”, “workload”, “pod” and “binary”.
tetragon.prometheus.portint2112The port at which to expose metrics.
tetragon.prometheus.serviceMonitor.enabledboolfalseWhether to create a ‘ServiceMonitor’ resource targeting the tetragon pods.
tetragon.prometheus.serviceMonitor.labelsOverrideobject{}The set of labels to place on the ‘ServiceMonitor’ resource.
tetragon.prometheus.serviceMonitor.scrapeIntervalstring"10s"Interval at which metrics should be scraped. If not specified, Prometheus’ global scrape interval is used.
tetragon.resourcesobject{}
tetragon.securityContext.privilegedbooltrue
tetragonOperatorobject{"affinity":{},"annotations":{},"enabled":true,"extraLabels":{},"extraPodLabels":{},"extraVolumeMounts":[],"extraVolumes":[],"image":{"override":null,"pullPolicy":"IfNotPresent","repository":"quay.io/cilium/tetragon-operator","tag":"v1.0.2"},"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.annotationsobject{}Annotations for the Tetragon Operator Deployment.
tetragonOperator.enabledbooltrueEnables the Tetragon Operator.
tetragonOperator.extraLabelsobject{}Extra labels to be added on the Tetragon Operator Deployment.
tetragonOperator.extraPodLabelsobject{}Extra labels to be added on the Tetragon Operator Deployment Pods.
tetragonOperator.extraVolumeslist[]Extra volumes for the Tetragon Operator Deployment.
tetragonOperator.imageobject{"override":null,"pullPolicy":"IfNotPresent","repository":"quay.io/cilium/tetragon-operator","tag":"v1.0.2"}tetragon-operator image.
tetragonOperator.nodeSelectorobject{}Steer the Tetragon Operator Deployment Pod placement via nodeSelector, tolerations and affinity rules.
tetragonOperator.podAnnotationsobject{}Annotations for the Tetragon Operator Deployment Pods.
tetragonOperator.podInfo.enabledboolfalseEnables the PodInfo CRD and the controller that reconciles PodInfo custom resources.
tetragonOperator.podSecurityContextobject{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}}securityContext for the Tetragon Operator Deployment Pod container.
tetragonOperator.priorityClassNamestring""priorityClassName for the Tetragon Operator Deployment Pods.
tetragonOperator.prometheusobject{"address":"","enabled":true,"port":2113,"serviceMonitor":{"enabled":false,"labelsOverride":{},"scrapeInterval":"10s"}}Enables the Tetragon Operator metrics.
tetragonOperator.prometheus.addressstring""The address at which to expose Tetragon Operator metrics. Set it to "" to expose on all available interfaces.
tetragonOperator.prometheus.portint2113The port at which to expose metrics.
tetragonOperator.prometheus.serviceMonitorobject{"enabled":false,"labelsOverride":{},"scrapeInterval":"10s"}The labels to include with supporting metrics.
tetragonOperator.prometheus.serviceMonitor.enabledboolfalseWhether to create a ‘ServiceMonitor’ resource targeting the tetragonOperator pods.
tetragonOperator.prometheus.serviceMonitor.labelsOverrideobject{}The set of labels to place on the ‘ServiceMonitor’ resource.
tetragonOperator.prometheus.serviceMonitor.scrapeIntervalstring"10s"Interval at which metrics should be scraped. If not specified, Prometheus’ global scrape interval is used.
tetragonOperator.resourcesobject{"limits":{"cpu":"500m","memory":"128Mi"},"requests":{"cpu":"10m","memory":"64Mi"}}resources for the Tetragon Operator Deployment Pod container.
tetragonOperator.securityContextobject{}securityContext for the Tetragon Operator Deployment Pods.
tetragonOperator.serviceAccountobject{"annotations":{},"create":true,"name":""}tetragon-operator service account.
tetragonOperator.strategyobject{}resources for the Tetragon Operator Deployment update strategy
tetragonOperator.tracingPolicy.enabledbooltrueEnables the TracingPolicy and TracingPolicyNamespaced CRD creation.
tolerations[0].operatorstring"Exists"
updateStrategyobject{}

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

NameNumberDescription
CAP_CHOWN0In a system with the [_POSIX_CHOWN_RESTRICTED] option defined, this overrides the restriction of changing file ownership and group ownership.
DAC_OVERRIDE1Override all DAC access, including ACL execute access if [_POSIX_ACL] is defined. Excluding DAC access covered by CAP_LINUX_IMMUTABLE.
CAP_DAC_READ_SEARCH2Overrides 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_FOWNER3Overrides 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_FSETID4Overrides 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_KILL5Overrides 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_SETGID6Allows forged gids on socket credentials passing.
CAP_SETUID7Allows forged pids on socket credentials passing.
CAP_SETPCAP8Without 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_IMMUTABLE9Allow modification of S_IMMUTABLE and S_APPEND file attributes
CAP_NET_BIND_SERVICE10Allows binding to ATM VCIs below 32
CAP_NET_BROADCAST11Allow broadcasting, listen to multicast
CAP_NET_ADMIN12Allow activation of ATM control sockets
CAP_NET_RAW13Allow binding to any address for transparent proxying (also via NET_ADMIN)
CAP_IPC_LOCK14Allow mlock and mlockall (which doesn't really have anything to do with IPC)
CAP_IPC_OWNER15Override IPC ownership checks
CAP_SYS_MODULE16Insert and remove kernel modules - modify kernel without limit
CAP_SYS_RAWIO17Allow sending USB messages to any device via /dev/bus/usb
CAP_SYS_CHROOT18Allow use of chroot()
CAP_SYS_PTRACE19Allow ptrace() of any process
CAP_SYS_PACCT20Allow configuration of process accounting
CAP_SYS_ADMIN21Allow everything under CAP_BPF and CAP_PERFMON for backward compatibility
CAP_SYS_BOOT22Allow use of reboot()
CAP_SYS_NICE23Allow setting cpu affinity on other processes
CAP_SYS_RESOURCE24Control memory reclaim behavior
CAP_SYS_TIME25Allow setting the real-time clock
CAP_SYS_TTY_CONFIG26Allow vhangup() of tty
CAP_MKNOD27Allow the privileged aspects of mknod()
CAP_LEASE28Allow taking of leases on files
CAP_AUDIT_WRITE29Allow writing the audit log via unicast netlink socket
CAP_AUDIT_CONTROL30Allow configuration of audit via unicast netlink socket
CAP_SETFCAP31Set or remove capabilities on files
CAP_MAC_OVERRIDE32Override 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_ADMIN33Allow 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_SYSLOG34Allow configuring the kernel's syslog (printk behaviour)
CAP_WAKE_ALARM35Allow triggering something that will wake the system
CAP_BLOCK_SUSPEND36Allow preventing system suspends
CAP_AUDIT_READ37Allow reading the audit log via multicast netlink socket
CAP_PERFMON38Allow system performance and observability privileged operations using perf_events, i915_perf and other kernel subsystems
CAP_BPF39CAP_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_RESTORE40Allow writing to ns_last_pid

ProcessPrivilegesChanged

Reasons of why the process privileges changed.

NameNumberDescription
PRIVILEGES_CHANGED_UNSET0
PRIVILEGES_RAISED_EXEC_FILE_CAP1A 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_SETUID2A 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_SETGID3A 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

NameNumberDescription
SecBitNotSet0
SecBitNoRoot1When 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.
SecBitNoRootLocked2Make bit-0 SecBitNoRoot immutable
SecBitNoSetUidFixup4When 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.
SecBitNoSetUidFixupLocked8Make bit-2 SecBitNoSetUidFixup immutable
SecBitKeepCaps16When 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.
SecBitKeepCapsLocked32Make bit-4 SecBitKeepCaps immutable
SecBitNoCapAmbientRaise64When set, a process cannot add new capabilities to its ambient set.
SecBitNoCapAmbientRaiseLocked128Make bit-6 SecBitNoCapAmbientRaise immutable

tetragon/tetragon.proto

BinaryProperties

FieldTypeLabelDescription
setuidgoogle.protobuf.UInt32ValueIf set then this is the set user ID used for execution
setgidgoogle.protobuf.UInt32ValueIf set then this is the set group ID used for execution
privileges_changedProcessPrivilegesChangedrepeatedThe 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.
fileFilePropertiesFile 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

FieldTypeLabelDescription
permittedCapabilitiesTyperepeatedPermitted 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.
effectiveCapabilitiesTyperepeatedEffective set indicates what capabilities are active in a process. This is the set used by the kernel to perform permission checks for the thread.
inheritableCapabilitiesTyperepeatedInheritable set indicates which capabilities will be inherited by the current process when running as a root user.

Container

FieldTypeLabelDescription
idstringIdentifier of the container.
namestringName of the container.
imageImageImage of the container.
start_timegoogle.protobuf.TimestampStart time of the container.
pidgoogle.protobuf.UInt32ValueProcess identifier in the container namespace.
maybe_exec_probeboolIf 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.

FieldTypeLabelDescription
cgroupsPathstringcgroupsPath 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
rootDirstringrootDir 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
annotationsCreateContainer.AnnotationsEntryrepeatedannotations are the run-time annotations for the container see https://github.com/opencontainers/runtime-spec/blob/main/config.md#annotations

CreateContainer.AnnotationsEntry

FieldTypeLabelDescription
keystring
valuestring

FileProperties

FieldTypeLabelDescription
inodeInodePropertiesInode of the file
pathstringPath of the file

GetHealthStatusRequest

FieldTypeLabelDescription
event_setHealthStatusTyperepeated

GetHealthStatusResponse

FieldTypeLabelDescription
health_statusHealthStatusrepeated

HealthStatus

FieldTypeLabelDescription
eventHealthStatusType
statusHealthStatusResult
detailsstring

Image

FieldTypeLabelDescription
idstringIdentifier of the container image composed of the registry path and the sha256.
namestringName of the container image composed of the registry path and the tag.

InodeProperties

FieldTypeLabelDescription
numberuint64The inode number
linksgoogle.protobuf.UInt32ValueThe inode links on the file system. If zero means the file is only in memory

KernelModule

FieldTypeLabelDescription
namestringKernel module name
signature_okgoogle.protobuf.BoolValueIf 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
taintedTaintedBitsTyperepeatedThe 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

FieldTypeLabelDescription
string_argstring
int_argint32
skb_argKprobeSkb
size_arguint64
bytes_argbytes
path_argKprobePath
file_argKprobeFile
truncated_bytes_argKprobeTruncatedBytes
sock_argKprobeSock
cred_argKprobeCred
long_argint64
bpf_attr_argKprobeBpfAttr
perf_event_argKprobePerfEvent
bpf_map_argKprobeBpfMap
uint_arguint32
user_namespace_argKprobeUserNamespaceDeprecated.
capability_argKprobeCapability
process_credentials_argProcessCredentials
user_ns_argUserNamespace
module_argKernelModule
kernel_cap_t_argstringCapabilities in hexadecimal format.
cap_inheritable_argstringCapabilities inherited by a forked process in hexadecimal format.
cap_permitted_argstringCapabilities that are currently permitted in hexadecimal format.
cap_effective_argstringCapabilities that are actually used in hexadecimal format.
linux_binprm_argKprobeLinuxBinprm
labelstring

KprobeBpfAttr

FieldTypeLabelDescription
ProgTypestring
InsnCntuint32
ProgNamestring

KprobeBpfMap

FieldTypeLabelDescription
MapTypestring
KeySizeuint32
ValueSizeuint32
MaxEntriesuint32
MapNamestring

KprobeCapability

FieldTypeLabelDescription
valuegoogle.protobuf.Int32Value
namestring

KprobeCred

FieldTypeLabelDescription
permittedCapabilitiesTyperepeated
effectiveCapabilitiesTyperepeated
inheritableCapabilitiesTyperepeated

KprobeFile

FieldTypeLabelDescription
mountstring
pathstring
flagsstring

KprobeLinuxBinprm

FieldTypeLabelDescription
pathstring

KprobePath

FieldTypeLabelDescription
mountstring
pathstring
flagsstring

KprobePerfEvent

FieldTypeLabelDescription
KprobeFuncstring
Typestring
Configuint64
ProbeOffsetuint64

KprobeSkb

FieldTypeLabelDescription
hashuint32
lenuint32
priorityuint32
markuint32
saddrstring
daddrstring
sportuint32
dportuint32
protouint32
sec_path_lenuint32
sec_path_olenuint32
protocolstring
familystring

KprobeSock

FieldTypeLabelDescription
familystring
typestring
protocolstring
markuint32
priorityuint32
saddrstring
daddrstring
sportuint32
dportuint32
cookieuint64
statestring

KprobeTruncatedBytes

FieldTypeLabelDescription
bytes_argbytes
orig_sizeuint64

KprobeUserNamespace

FieldTypeLabelDescription
levelgoogle.protobuf.Int32Value
ownergoogle.protobuf.UInt32Value
groupgoogle.protobuf.UInt32Value
nsNamespace

Namespace

FieldTypeLabelDescription
inumuint32Inode number of the namespace.
is_hostboolIndicates if namespace belongs to host.

Namespaces

FieldTypeLabelDescription
utsNamespaceHostname and NIS domain name.
ipcNamespaceSystem V IPC, POSIX message queues.
mntNamespaceMount points.
pidNamespaceProcess IDs.
pid_for_childrenNamespaceProcess IDs for children processes.
netNamespaceNetwork devices, stacks, ports, etc.
timeNamespaceBoot and monotonic clocks.
time_for_childrenNamespaceBoot and monotonic clocks for children processes.
cgroupNamespaceCgroup root directory.
userNamespaceUser and group IDs.

Pod

FieldTypeLabelDescription
namespacestringKubernetes namespace of the Pod.
namestringName of the Pod.
containerContainerContainer of the Pod from which the process that triggered the event originates.
pod_labelsPod.PodLabelsEntryrepeatedContains all the labels of the pod.
workloadstringKubernetes workload of the Pod.
workload_kindstringKubernetes workload kind (e.g. "Deployment", "DaemonSet") of the Pod.

Pod.PodLabelsEntry

FieldTypeLabelDescription
keystring
valuestring

Process

FieldTypeLabelDescription
exec_idstringExec ID uniquely identifies the process over time across all the nodes in the cluster.
pidgoogle.protobuf.UInt32ValueProcess identifier from host PID namespace.
uidgoogle.protobuf.UInt32ValueUser identifier associated with the process.
cwdstringCurrent working directory of the process.
binarystringAbsolute path of the executed binary.
argumentsstringArguments passed to the binary at execution.
flagsstringFlags 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_timegoogle.protobuf.TimestampStart time of the execution.
auidgoogle.protobuf.UInt32ValueAudit 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.
podPodInformation about the the Kubernetes Pod where the event originated.
dockerstringThe 15 first digits of the container ID.
parent_exec_idstringExec ID of the parent process.
refcntuint32Reference counter from the Tetragon process cache.
capCapabilitiesSet of capabilities that define the permissions the process can execute with.
nsNamespacesLinux namespaces of the process, disabled by default, can be enabled by the --enable-process-ns flag.
tidgoogle.protobuf.UInt32ValueThread ID, note that for the thread group leader, tid is equal to pid.
process_credentialsProcessCredentialsProcess credentials
binary_propertiesBinaryPropertiesExecuted binary properties. This field is only available on ProcessExec events.

ProcessCredentials

FieldTypeLabelDescription
uidgoogle.protobuf.UInt32ValueThe real user ID
gidgoogle.protobuf.UInt32ValueThe real group ID
euidgoogle.protobuf.UInt32ValueThe effective user ID
egidgoogle.protobuf.UInt32ValueThe effective group ID
suidgoogle.protobuf.UInt32ValueThe saved user ID
sgidgoogle.protobuf.UInt32ValueThe saved group ID
fsuidgoogle.protobuf.UInt32Valuethe filesystem user ID
fsgidgoogle.protobuf.UInt32ValueThe filesystem group ID
securebitsSecureBitsTyperepeatedSecure management flags
capsCapabilitiesSet of capabilities that define the permissions the process can execute with.
user_nsUserNamespaceUser namespace where the UIDs, GIDs and capabilities are relative to.

ProcessExec

FieldTypeLabelDescription
processProcessProcess that triggered the exec.
parentProcessImmediate parent of the process.
ancestorsProcessrepeatedAncestors of the process beyond the immediate parent.

ProcessExit

FieldTypeLabelDescription
processProcessProcess that triggered the exit.
parentProcessImmediate parent of the process.
signalstringSignal 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.
statusuint32Status code on process exit. For example, the status code can indicate if an error was encountered or the program exited successfully.
timegoogle.protobuf.TimestampDate and time of the event.

ProcessKprobe

FieldTypeLabelDescription
processProcessProcess that triggered the kprobe.
parentProcessImmediate parent of the process.
function_namestringSymbol on which the kprobe was attached.
argsKprobeArgumentrepeatedArguments definition of the observed kprobe.
returnKprobeArgumentReturn value definition of the observed kprobe.
actionKprobeActionAction performed when the kprobe matched.
stack_traceStackTraceEntryrepeatedKernel stack trace to the call.
policy_namestringName of the Tracing Policy that created that kprobe.
return_actionKprobeActionAction performed when the return kprobe executed.
messagestringShort message of the Tracing Policy to inform users what is going on.

ProcessLoader

loader sensor event triggered for loaded binary/library

FieldTypeLabelDescription
processProcess
pathstring
buildidbytes

ProcessTracepoint

FieldTypeLabelDescription
processProcessProcess that triggered the tracepoint.
parentProcessImmediate parent of the process.
subsysstringSubsystem of the tracepoint.
eventstringEvent of the subsystem.
argsKprobeArgumentrepeatedArguments definition of the observed tracepoint. TODO: once we implement all we want, rename KprobeArgument to GenericArgument
policy_namestringName of the policy that created that tracepoint.
actionKprobeActionAction performed when the tracepoint matched.
messagestringShort message of the Tracing Policy to inform users what is going on.

ProcessUprobe

FieldTypeLabelDescription
processProcess
parentProcess
pathstring
symbolstring
policy_namestringName of the policy that created that uprobe.
messagestringShort message of the Tracing Policy to inform users what is going on.
argsKprobeArgumentrepeatedArguments definition of the observed uprobe.

RuntimeHookRequest

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

FieldTypeLabelDescription
createContainerCreateContainer

RuntimeHookResponse

StackTraceEntry

FieldTypeLabelDescription
addressuint64address is the kernel function address.
offsetuint64offset is the offset into the native instructions for the function.
symbolstringsymbol is the symbol name of the function.

Test

FieldTypeLabelDescription
arg0uint64
arg1uint64
arg2uint64
arg3uint64

UserNamespace

FieldTypeLabelDescription
levelgoogle.protobuf.Int32ValueNested level of the user namespace. Init or host user namespace is at level 0.
uidgoogle.protobuf.UInt32ValueThe owner user ID of the namespace
gidgoogle.protobuf.UInt32ValueThe owner group ID of the namepace.
nsNamespaceThe user namespace details that include the inode number of the namespace.

HealthStatusResult

NameNumberDescription
HEALTH_STATUS_UNDEF0
HEALTH_STATUS_RUNNING1
HEALTH_STATUS_STOPPED2
HEALTH_STATUS_ERROR3

HealthStatusType

NameNumberDescription
HEALTH_STATUS_TYPE_UNDEF0
HEALTH_STATUS_TYPE_STATUS1

KprobeAction

NameNumberDescription
KPROBE_ACTION_UNKNOWN0Unknown action
KPROBE_ACTION_POST1Post action creates an event (default action).
KPROBE_ACTION_FOLLOWFD2Post action creates a mapping between file descriptors and file names.
KPROBE_ACTION_SIGKILL3Sigkill action synchronously terminates the process.
KPROBE_ACTION_UNFOLLOWFD4Post action removes a mapping between file descriptors and file names.
KPROBE_ACTION_OVERRIDE5Override action modifies the return value of the call.
KPROBE_ACTION_COPYFD6Post action dupplicates a mapping between file descriptors and file names.
KPROBE_ACTION_GETURL7GetURL action issue an HTTP Get request against an URL from userspace.
KPROBE_ACTION_DNSLOOKUP8GetURL action issue a DNS lookup against an URL from userspace.
KPROBE_ACTION_NOPOST9NoPost action suppresses the transmission of the event to userspace.
KPROBE_ACTION_SIGNAL10Signal action sends specified signal to the process.
KPROBE_ACTION_TRACKSOCK11TrackSock action tracks socket.
KPROBE_ACTION_UNTRACKSOCK12UntrackSock action un-tracks socket.
KPROBE_ACTION_NOTIFYENFORCER13NotifyEnforcer 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

NameNumberDescription
TAINT_UNSET0
TAINT_PROPRIETARY_MODULE1A proprietary module was loaded.
TAINT_FORCED_MODULE2A module was force loaded.
TAINT_FORCED_UNLOAD_MODULE4A module was force unloaded.
TAINT_STAGED_MODULE1024A staging driver was loaded.
TAINT_OUT_OF_TREE_MODULE4096An out of tree module was loaded.
TAINT_UNSIGNED_MODULE8192An unsigned module was loaded. Supported only on kernels built with CONFIG_MODULE_SIG option.
TAINT_KERNEL_LIVE_PATCH_MODULE32768The kernel has been live patched.
TAINT_TEST_MODULE262144Loading a test module.

tetragon/events.proto

AggregationInfo

AggregationInfo contains information about aggregation results.

FieldTypeLabelDescription
countuint64Total count of events in this aggregation time window.

AggregationOptions

AggregationOptions defines configuration options for aggregating events.

FieldTypeLabelDescription
window_sizegoogle.protobuf.DurationAggregation window size. Defaults to 15 seconds if this field is not set.
channel_buffer_sizeuint64Size 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.

FieldTypeLabelDescription
permittedCapFilterSetFilter over the set of permitted capabilities.
effectiveCapFilterSetFilter over the set of effective capabilities.
inheritableCapFilterSetFilter over the set of inheritable capabilities.

CapFilterSet

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

FieldTypeLabelDescription
anyCapabilitiesTyperepeatedMatch if the capability set contains any of the capabilities defined in this filter.
allCapabilitiesTyperepeatedMatch if the capability set contains all of the capabilities defined in this filter.
exactlyCapabilitiesTyperepeatedMatch if the capability set exactly matches all of the capabilities defined in this filter.
noneCapabilitiesTyperepeatedMatch if the capability set contains none of the capabilities defined in this filter.

FieldFilter

FieldTypeLabelDescription
event_setEventTyperepeatedEvent types to filter or undefined to filter over all event types.
fieldsgoogle.protobuf.FieldMaskFields to include or exclude.
actionFieldFilterActionWhether to include or exclude fields.
invert_event_setgoogle.protobuf.BoolValueWhether or not the event set filter should be inverted.

Filter

FieldTypeLabelDescription
binary_regexstringrepeated
namespacestringrepeated
health_checkgoogle.protobuf.BoolValue
piduint32repeated
pid_setuint32repeatedFilter 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_setEventTyperepeated
pod_regexstringrepeatedFilter by process.pod.name field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax
arguments_regexstringrepeatedFilter by process.arguments field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax
labelsstringrepeatedFilter 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_namesstringrepeatedFilter events by tracing policy names
capabilitiesCapFilterFilter events by Linux process capability

GetEventsRequest

FieldTypeLabelDescription
allow_listFilterrepeatedallow_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_listFilterrepeateddeny_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_optionsAggregationOptionsaggregation_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_filtersFieldFilterrepeatedFields 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

FieldTypeLabelDescription
process_execProcessExecProcessExec event includes information about the execution of binaries and other related process metadata.
process_exitProcessExitProcessExit event indicates how and when a process terminates.
process_kprobeProcessKprobeProcessKprobe event contains information about the pre-defined functions and the process that invoked them.
process_tracepointProcessTracepointProcessTracepoint contains information about the pre-defined tracepoint and the process that invoked them.
process_loaderProcessLoader
process_uprobeProcessUprobe
testTest
rate_limit_infoRateLimitInfo
node_namestringName of the node where this event was observed.
timegoogle.protobuf.TimestampTimestamp 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_infoAggregationInfoaggregation_info contains information about aggregation results. This field is set only for aggregated responses.

RateLimitInfo

FieldTypeLabelDescription
number_of_dropped_process_eventsuint64

EventType

Represents the type of a Tetragon event.

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

NameNumberDescription
UNDEF0
PROCESS_EXEC1
PROCESS_EXIT5
PROCESS_KPROBE9
PROCESS_TRACEPOINT10
PROCESS_LOADER11
PROCESS_UPROBE12
TEST40000
RATE_LIMIT_INFO40001

FieldFilterAction

Determines the behavior of a field filter

NameNumberDescription
INCLUDE0
EXCLUDE1

tetragon/stack.proto

StackAddress

FieldTypeLabelDescription
addressuint64
symbolstring

StackTrace

FieldTypeLabelDescription
addressesStackAddressrepeated

StackTraceLabel

FieldTypeLabelDescription
keystring
countuint64

StackTraceNode

FieldTypeLabelDescription
addressStackAddress
countuint64
labelsStackTraceLabelrepeated
childrenStackTraceNoderepeated

tetragon/sensors.proto

AddTracingPolicyRequest

FieldTypeLabelDescription
yamlstring

AddTracingPolicyResponse

DeleteTracingPolicyRequest

FieldTypeLabelDescription
namestring

DeleteTracingPolicyResponse

DisableSensorRequest

FieldTypeLabelDescription
namestring

DisableSensorResponse

DisableTracingPolicyRequest

FieldTypeLabelDescription
namestring

DisableTracingPolicyResponse

EnableSensorRequest

FieldTypeLabelDescription
namestring

EnableSensorResponse

EnableTracingPolicyRequest

FieldTypeLabelDescription
namestring

EnableTracingPolicyResponse

GetStackTraceTreeRequest

FieldTypeLabelDescription
namestring

GetStackTraceTreeResponse

FieldTypeLabelDescription
rootStackTraceNode

GetVersionRequest

GetVersionResponse

FieldTypeLabelDescription
versionstring

ListSensorsRequest

ListSensorsResponse

FieldTypeLabelDescription
sensorsSensorStatusrepeated

ListTracingPoliciesRequest

ListTracingPoliciesResponse

FieldTypeLabelDescription
policiesTracingPolicyStatusrepeated

RemoveSensorRequest

FieldTypeLabelDescription
namestring

RemoveSensorResponse

SensorStatus

FieldTypeLabelDescription
namestringname is the name of the sensor
enabledboolenabled marks whether the sensor is enabled
collectionstringcollection is the collection the sensor belongs to (typically a tracing policy)

TracingPolicyStatus

FieldTypeLabelDescription
iduint64id is the id of the policy
namestringname is the name of the policy
namespacestringnamespace is the namespace of the policy (or empty of the policy is global)
infostringinfo is additional information about the policy
sensorsstringrepeatedsensors loaded in the scope of this policy
enabledboolDeprecated. indicating if the policy is enabled. Deprecated: use 'state' instead.
filter_iduint64filter ID of the policy used for k8s filtering
errorstringpotential error of the policy
stateTracingPolicyStatecurrent state of the tracing policy

TracingPolicyState

NameNumberDescription
TP_STATE_UNKNOWN0unknown state
TP_STATE_ENABLED1loaded and enabled
TP_STATE_DISABLED2loaded but disabled
TP_STATE_LOAD_ERROR3failed to load
TP_STATE_ERROR4failed during lifetime

FineGuidanceSensors

Method NameRequest TypeResponse TypeDescription
GetEventsGetEventsRequestGetEventsResponse stream
GetHealthGetHealthStatusRequestGetHealthStatusResponse
AddTracingPolicyAddTracingPolicyRequestAddTracingPolicyResponse
DeleteTracingPolicyDeleteTracingPolicyRequestDeleteTracingPolicyResponse
RemoveSensorRemoveSensorRequestRemoveSensorResponse
ListTracingPoliciesListTracingPoliciesRequestListTracingPoliciesResponse
EnableTracingPolicyEnableTracingPolicyRequestEnableTracingPolicyResponse
DisableTracingPolicyDisableTracingPolicyRequestDisableTracingPolicyResponse
ListSensorsListSensorsRequestListSensorsResponse
EnableSensorEnableSensorRequestEnableSensorResponse
DisableSensorDisableSensorRequestDisableSensorResponse
GetStackTraceTreeGetStackTraceTreeRequestGetStackTraceTreeResponse
GetVersionGetVersionRequestGetVersionResponse
RuntimeHookRuntimeHookRequestRuntimeHookResponse

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)

4 - Metrics

This reference is autogenerated from the Tetragon Prometheus metrics registry.

Tetragon Health Metrics

tetragon_build_info

Build information about tetragon

labelvalues
commit931b70f2c9878ba985ba6b589827bea17da6ec33
go_versiongo1.22.0
modifiedfalse
time2022-05-13T15:54:45Z

tetragon_data_event_size

The size of received data events.

labelvalues
opbad, ok

tetragon_data_events_total

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

labelvalues
eventAdded, Appended, Bad, Matched, NotMatched, Received

tetragon_errors_total

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

labelvalues
typeevent_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_errors_total

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

labelvalues
errornil_process_pid
event_typePROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, 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.

labelvalues
event_typePROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, 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.

labelvalues
event_typePROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, 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.

labelvalues
event_typePROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO

tetragon_event_cache_retries_total

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

labelvalues
entry_typeparent_info, pod_info, process_info

tetragon_flags_total

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

labelvalues
typeauid, 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.

labelvalues
curr_fnexample_kprobe
curr_typeenter, exit
prev_fnexample_kprobe
prev_typeenter, 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.

labelvalues
error_typeevent_handler_failed, unknown_opcode
opcode0, 11, 13, 14, 15, 23, 24, 25, 26, 5, 7

tetragon_handling_latency

The latency of handling messages in us.

labelvalues
op11, 13, 14, 15, 23, 24, 25, 26, 5, 7

tetragon_map_errors_total

The number of errors per map.

labelvalues
mapexecve_map, tg_execve_joined_info_map

tetragon_map_in_use_gauge

The total number of in-use entries per map.

labelvalues
mapexecve_map, tg_execve_joined_info_map
total0

tetragon_missed_events_total

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

labelvalues
msg_op11, 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.

labelvalues
msg_op11, 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_metrics_total

Policy filter metrics. For internal use only.

labelvalues
opadd, add-container, delete, update
subsyspod-handlers, rthooks

tetragon_process_loader_stats

Process Loader event statistics. For internal use only.

labelvalues
countLoaderReceived, 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.

labelvalues
statedisabled, enabled, error, load_error

tetragon_watcher_errors_total

The total number of errors for a given watcher type.

labelvalues
errorfailed_to_get_pod
watcherk8s

tetragon_watcher_events_total

The total number of events for a given watcher type.

labelvalues
watcherk8s

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.

labelvalues
versiongo1.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

labelvalues
binaryexample-binary
namespaceexample-namespace
podexample-pod
typePROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO
workloadexample-workload

tetragon_policy_events_total

Policy events calls observed.

labelvalues
binaryexample-binary
hookexample_kprobe
namespaceexample-namespace
podexample-pod
policyexample-tracingpolicy
workloadexample-workload

tetragon_syscalls_total

System calls observed.

labelvalues
binaryexample-binary
namespaceexample-namespace
podexample-pod
syscallexample_syscall
workloadexample-workload