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.

Flag Usage Default Value
--bpf-dir Set tetragon bpf directory (default 'tetragon') tetragon
--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)
--cluster-name Name of the cluster where Tetragon is installed
--config-dir Configuration directory that contains a file for each option
--cpuprofile Store CPU profile into provided file
--cri-endpoint CRI endpoint
--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-cgidmap enable pod resolution via cgroup ids false
--enable-cgidmap-debug enable cgidmap debugging info false
--enable-compatibility-syscall64-size-type syscall64 type will produce output of type size (compatibility flag, will be removed in v1.4) false
--enable-cri enable CRI client for tetragon 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 false
--enable-policy-filter-debug Enable policy filter debug messages false
--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-cache-retries Number of retries for event cache 15
--event-cache-retry-delay Delay in seconds between event cache retries 2
--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-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
--health-server-address Health server address (e.g. ':6789')(use '' to disabled it) :6789
--health-server-interval Health server interval in seconds 10
--help help for tetragon false
--k8s-kubeconfig-path Absolute path of the kubernetes kubeconfig file
--keep-sensors-on-exit Do not unload sensors on exit false
--kernel Kernel version
--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-address Serves runtime profile data via HTTP (e.g. 'localhost:6060'). Disabled by default
--process-cache-gc-interval Time between checking the process cache for old entries 30s
--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'). An empty address disables the gRPC server 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:

  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

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" DNS policy for Tetragon pods. https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy
enabled bool true
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 events export settings
exportDirectory string "/var/run/cilium/tetragon" Directory to put Tetragon JSON export files.
extraConfigmapMounts list []
extraHostPathMounts list []
extraVolumes list []
hostNetwork bool true Configures whether Tetragon pods run on the host network. IMPORTANT: Tetragon must be on the host network for the process visibility to function properly.
imagePullPolicy string "IfNotPresent"
imagePullSecrets list []
nodeSelector object {}
podAnnotations object {}
podLabels object {}
podLabelsOverride object {}
podSecurityContext object {}
priorityClassName string ""
rthooks object {"annotations":{},"enabled":false,"extraHookArgs":{},"extraLabels":{},"extraVolumeMounts":[],"failAllowNamespaces":"","image":{"override":null,"repository":"quay.io/cilium/tetragon-rthooks","tag":"v0.4"},"installDir":"/opt/tetragon","interface":"","nriHook":{"nriSocket":"/var/run/nri/nri.sock"},"ociHooks":{"hooksPath":"/usr/share/containers/oci/hooks.d"},"podAnnotations":{},"podSecurityContext":{},"priorityClassName":"","resources":{},"serviceAccount":{"name":""}} Method for installing Tetagon rthooks (tetragon-rthooks) daemonset The tetragon-rthooks daemonset is responsible for installing run-time hooks on the host. See: https://tetragon.io/docs/concepts/runtime-hooks
rthooks.annotations object {} Annotations for the Tetragon rthooks daemonset
rthooks.enabled bool false Enable the Tetragon rthooks daemonset
rthooks.extraHookArgs object {} extra args to pass to tetragon-oci-hook
rthooks.extraLabels object {} Extra labels for the Tetrargon rthooks daemonset
rthooks.extraVolumeMounts list [] Extra volume mounts to add to the oci-hook-setup init container
rthooks.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.
rthooks.image object {"override":null,"repository":"quay.io/cilium/tetragon-rthooks","tag":"v0.4"} image for the Tetragon rthooks pod
rthooks.installDir string "/opt/tetragon" installDir is the host location where the tetragon-oci-hook binary will be installed
rthooks.interface string "" Method to use for installing rthooks. Values: “oci-hooks”: Add an apppriate file to “/usr/share/containers/oci/hooks.d”. Use this with CRI-O. See https://github.com/containers/common/blob/main/pkg/hooks/docs/oci-hooks.5.md for more details. Specific configuration for this interface can be found under “OciHooks”. “nri-hook”: Install the hook via NRI. Use this with containerd. Requires NRI being enabled. see: https://github.com/containerd/containerd/blob/main/docs/NRI.md.
rthooks.nriHook object {"nriSocket":"/var/run/nri/nri.sock"} configuration for the “nri-hook” interface
rthooks.nriHook.nriSocket string "/var/run/nri/nri.sock" path to NRI socket
rthooks.ociHooks object {"hooksPath":"/usr/share/containers/oci/hooks.d"} configuration for “oci-hooks” interface
rthooks.ociHooks.hooksPath string "/usr/share/containers/oci/hooks.d" directory to install .json file for running the hook
rthooks.podAnnotations object {} Pod annotations for the Tetrargon rthooks pod
rthooks.podSecurityContext object {} security context for the Tetrargon rthooks pod
rthooks.priorityClassName string "" priorityClassName for the Tetrargon rthooks pod
rthooks.resources object {} resources for the the oci-hook-setup init container
rthooks.serviceAccount object {"name":""} rthooks service account.
selectorLabelsOverride object {}
serviceAccount.annotations object {}
serviceAccount.create bool true
serviceAccount.name string ""
serviceLabelsOverride object {}
tetragon.argsOverride list [] Override the arguments. For advanced users only.
tetragon.btf string ""
tetragon.clusterName string "" Name of the cluster where Tetragon is installed. Tetragon uses this value to set the cluster_name field in GetEventsResponse messages.
tetragon.commandOverride list [] Override the command. For advanced users only.
tetragon.debug bool false If you want to run Tetragon in debug mode change this value to true
tetragon.enableK8sAPI bool true Access Kubernetes API to associate Tetragon events with Kubernetes pods.
tetragon.enableKeepSensorsOnExit bool false Persistent enforcement to allow the enforcement policy to continue running even when its Tetragon process is gone.
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 Enable Capabilities visibility in exec and kprobe events.
tetragon.enableProcessNs bool false Enable Namespaces visibility in exec and kprobe events.
tetragon.enabled bool true
tetragon.eventCacheRetries int 15 Configure the number of retries in tetragon’s event cache.
tetragon.eventCacheRetryDelay int 2 Configure the delay (in seconds) between retires in tetragon’s event cache.
tetragon.exportAllowList string "{\"event_set\":[\"PROCESS_EXEC\", \"PROCESS_EXIT\", \"PROCESS_KPROBE\", \"PROCESS_UPROBE\", \"PROCESS_TRACEPOINT\", \"PROCESS_LSM\"]}" Allowlist for JSON export. For example, to export only process_connect events from the default namespace: exportAllowList:
tetragon.exportDenyList string "{\"health_check\":true}\n{\"namespace\":[\"\", \"cilium\", \"kube-system\"]}" Denylist for JSON export. For example, to exclude exec events that look similar to Kubernetes health checks and all the events from kube-system namespace and the host: exportDenyList:
tetragon.exportFileCompress bool false Compress rotated JSON export files.
tetragon.exportFileMaxBackups int 5 Number of rotated files to retain.
tetragon.exportFileMaxSizeMB int 10 Size in megabytes at which to rotate JSON export files.
tetragon.exportFilePerm string "600" JSON export file permissions as a string. Typically it’s either “600” (to restrict access to owner) or “640”/“644” (to allow read access by logs collector or another agent).
tetragon.exportFilename string "tetragon.log" JSON export filename. Set it to an empty string to disable JSON export altogether.
tetragon.exportRateLimit int -1 Rate-limit event export (events per minute), Set to -1 to export all events.
tetragon.extraArgs object {}
tetragon.extraEnv list []
tetragon.extraVolumeMounts list []
tetragon.fieldFilters string "" Filters to include or exclude fields from Tetragon events. Without any filters, all fields are included by default. The presence of at least one inclusion filter implies default-exclude (i.e. any fields that don’t match an inclusion filter will be excluded). Field paths are expressed using dot notation like “a.b.c” and multiple field paths can be separated by commas like “a.b.c,d,e.f”. An optional “event_set” may be specified to apply the field filter to a specific set of events. For example, to exclude the “parent” field from all events and include the “process” field in PROCESS_KPROBE events while excluding all others: fieldFilters:
tetragon.gops.address string "localhost" The address at which to expose gops.
tetragon.gops.enabled bool true Whether to enable exposing gops server.
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/cilum/tetragon/tetragon.sock
tetragon.grpc.enabled bool true Whether to enable exposing Tetragon gRPC.
tetragon.healthGrpc.enabled bool true Whether to enable health gRPC server.
tetragon.healthGrpc.interval int 10 The interval at which to check the health of the agent.
tetragon.healthGrpc.port int 6789 The port at which to expose health 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.2.0"
tetragon.livenessProbe object {} Overrides the default livenessProbe for the tetragon container.
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 NOTE: This is deprecated, please use .rthooks
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.pprof.address string "localhost" The address at which to expose pprof.
tetragon.pprof.enabled bool false Whether to enable exposing pprof server.
tetragon.pprof.port int 6060 The port at which to expose pprof.
tetragon.processCacheGCInterval string "30s" Configure the interval (suffixed with s for seconds, m for minutes, etc) for the process cache garbage collector.
tetragon.processCacheSize int 65536 Tetragon puts processes in an LRU cache. The cache is used to find ancestors for subsequently exec’ed processes.
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.extraLabels object {} Extra labels to be added on the Tetragon ServiceMonitor.
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 "" Filters to redact secrets from the args fields in Tetragon events. To perform redactions, redaction filters define RE2 regular expressions in the redact field. Any capture groups in these RE2 regular expressions are redacted and replaced with “*****”. For more control, you can select which binary or binaries should have their arguments redacted with the binary_regex field. NOTE: This feature uses RE2 as its regular expression library. Make sure that you follow RE2 regular expression guidelines as you may observe unexpected results otherwise. More information on RE2 syntax can be found here. NOTE: When writing regular expressions in JSON, it is important to escape backslash characters. For instance \Wpasswd\W? would be written as {"redact": "\\Wpasswd\\W?"}. As a concrete example, the following will redact all passwords passed to processes with the “–password” argument: {“redact”: ["–password(?:\s+
tetragon.resources object {}
tetragon.securityContext.privileged bool true
tetragonOperator.affinity object {}
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.extraVolumeMounts list []
tetragonOperator.extraVolumes list [] Extra volumes for the Tetragon Operator Deployment.
tetragonOperator.forceUpdateCRDs bool false
tetragonOperator.image object {"override":null,"pullPolicy":"IfNotPresent","repository":"quay.io/cilium/tetragon-operator","tag":"v1.2.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.address string "" The address at which to expose Tetragon Operator metrics. Set it to "" to expose on all available interfaces.
tetragonOperator.prometheus.enabled bool true Enables the Tetragon Operator metrics.
tetragonOperator.prometheus.port int 2113 The port at which to expose metrics.
tetragonOperator.prometheus.serviceMonitor.enabled bool false Whether to create a ‘ServiceMonitor’ resource targeting the tetragonOperator pods.
tetragonOperator.prometheus.serviceMonitor.extraLabels object {} Extra labels to be added on the Tetragon Operator ServiceMonitor.
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.strategy object {} resources for the Tetragon Operator Deployment update strategy
tetragonOperator.tolerations[0].operator string "Exists"
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/bpf.proto

BpfCmd

Name Number Description
BPF_MAP_CREATE 0 Create a map and return a file descriptor that refers to the map.
BPF_MAP_LOOKUP_ELEM 1 Look up an element with a given key in the map referred to by the file descriptor map_fd.
BPF_MAP_UPDATE_ELEM 2 Create or update an element (key/value pair) in a specified map.
BPF_MAP_DELETE_ELEM 3 Look up and delete an element by key in a specified map.
BPF_MAP_GET_NEXT_KEY 4 Look up an element by key in a specified map and return the key of the next element. Can be used to iterate over all elements in the map.
BPF_PROG_LOAD 5 Verify and load an eBPF program, returning a new file descriptor associated with the program.
BPF_OBJ_PIN 6 Pin an eBPF program or map referred by the specified bpf_fd to the provided pathname on the filesystem.
BPF_OBJ_GET 7 Open a file descriptor for the eBPF object pinned to the specified pathname.
BPF_PROG_ATTACH 8 Attach an eBPF program to a target_fd at the specified attach_type hook.
BPF_PROG_DETACH 9 Detach the eBPF program associated with the target_fd at the hook specified by attach_type.
BPF_PROG_TEST_RUN 10 Run the eBPF program associated with the prog_fd a repeat number of times against a provided program context ctx_in and data data_in, and return the modified program context ctx_out, data_out (for example, packet data), result of the execution retval, and duration of the test run.
BPF_PROG_GET_NEXT_ID 11 Fetch the next eBPF program currently loaded into the kernel.
BPF_MAP_GET_NEXT_ID 12 Fetch the next eBPF map currently loaded into the kernel.
BPF_PROG_GET_FD_BY_ID 13 Open a file descriptor for the eBPF program corresponding to prog_id.
BPF_MAP_GET_FD_BY_ID 14 Open a file descriptor for the eBPF map corresponding to map_id.
BPF_OBJ_GET_INFO_BY_FD 15 Obtain information about the eBPF object corresponding to bpf_fd.
BPF_PROG_QUERY 16 Obtain information about eBPF programs associated with the specified attach_type hook.
BPF_RAW_TRACEPOINT_OPEN 17 Attach an eBPF program to a tracepoint name to access kernel internal arguments of the tracepoint in their raw form.
BPF_BTF_LOAD 18 Verify and load BPF Type Format (BTF) metadata into the kernel, returning a new file descriptor associated with the metadata.
BPF_BTF_GET_FD_BY_ID 19 Open a file descriptor for the BPF Type Format (BTF) corresponding to btf_id.
BPF_TASK_FD_QUERY 20 Obtain information about eBPF programs associated with the target process identified by pid and fd.
BPF_MAP_LOOKUP_AND_DELETE_ELEM 21 Look up an element with the given key in the map referred to by the file descriptor fd, and if found, delete the element.
BPF_MAP_FREEZE 22 Freeze the permissions of the specified map.
BPF_BTF_GET_NEXT_ID 23 Fetch the next BPF Type Format (BTF) object currently loaded into the kernel.
BPF_MAP_LOOKUP_BATCH 24 Iterate and fetch multiple elements in a map.
BPF_MAP_LOOKUP_AND_DELETE_BATCH 25 Iterate and delete all elements in a map.
BPF_MAP_UPDATE_BATCH 26 Update multiple elements in a map by key.
BPF_MAP_DELETE_BATCH 27 Delete multiple elements in a map by key.
BPF_LINK_CREATE 28 Attach an eBPF program to a target_fd at the specified attach_type hook and return a file descriptor handle for managing the link.
BPF_LINK_UPDATE 29 Update the eBPF program in the specified link_fd to new_prog_fd.
BPF_LINK_GET_FD_BY_ID 30 Open a file descriptor for the eBPF Link corresponding to link_id.
BPF_LINK_GET_NEXT_ID 31 Fetch the next eBPF link currently loaded into the kernel.
BPF_ENABLE_STATS 32 Enable eBPF runtime statistics gathering.
BPF_ITER_CREATE 33 Create an iterator on top of the specified link_fd (as previously created using BPF_LINK_CREATE) and return a file descriptor that can be used to trigger the iteration.
BPF_LINK_DETACH 34 Forcefully detach the specified link_fd from its corresponding attachment point.
BPF_PROG_BIND_MAP 35 Bind a map to the lifetime of an eBPF program.
BPF_TOKEN_CREATE 36 Create BPF token with embedded information about what can be passed as an extra parameter to various bpf() syscall commands to grant BPF subsystem functionality to unprivileged processes.

BpfProgramType

Name Number Description
BPF_PROG_TYPE_UNSPEC 0
BPF_PROG_TYPE_SOCKET_FILTER 1
BPF_PROG_TYPE_KPROBE 2
BPF_PROG_TYPE_SCHED_CLS 3
BPF_PROG_TYPE_SCHED_ACT 4
BPF_PROG_TYPE_TRACEPOINT 5
BPF_PROG_TYPE_XDP 6
BPF_PROG_TYPE_PERF_EVENT 7
BPF_PROG_TYPE_CGROUP_SKB 8
BPF_PROG_TYPE_CGROUP_SOCK 9
BPF_PROG_TYPE_LWT_IN 10
BPF_PROG_TYPE_LWT_OUT 11
BPF_PROG_TYPE_LWT_XMIT 12
BPF_PROG_TYPE_SOCK_OPS 13
BPF_PROG_TYPE_SK_SKB 14
BPF_PROG_TYPE_CGROUP_DEVICE 15
BPF_PROG_TYPE_SK_MSG 16
BPF_PROG_TYPE_RAW_TRACEPOINT 17
BPF_PROG_TYPE_CGROUP_SOCK_ADDR 18
BPF_PROG_TYPE_LWT_SEG6LOCAL 19
BPF_PROG_TYPE_LIRC_MODE2 20
BPF_PROG_TYPE_SK_REUSEPORT 21
BPF_PROG_TYPE_FLOW_DISSECTOR 22
BPF_PROG_TYPE_CGROUP_SYSCTL 23
BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE 24
BPF_PROG_TYPE_CGROUP_SOCKOPT 25
BPF_PROG_TYPE_TRACING 26
BPF_PROG_TYPE_STRUCT_OPS 27
BPF_PROG_TYPE_EXT 28
BPF_PROG_TYPE_LSM 29
BPF_PROG_TYPE_SK_LOOKUP 30
BPF_PROG_TYPE_SYSCALL 31
BPF_PROG_TYPE_NETFILTER 32

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 Label 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.

The containerName, containerID, podName, podUID, and podNamespace fields are retrieved from the annotations as a convenience, and may be left empty if the corresponding annotations are not found.

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
containerID string containerID is the id of the container
podName string podName is the pod name
podUID string podUID is the pod uid
podNamespace string podNamespace is the namespace of the pod

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 Label 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
bpf_cmd_arg BpfCmd
syscall_id SyscallId
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 Description
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 Label 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 Label 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 The effective User identifier used for permission checks. This field maps to the 'ProcessCredentials.euid' field. Run with the --enable-process-cred flag to enable 'ProcessCredentials' and get all the User and Group identifiers.
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, disabled by default, can be enabled by the --enable-process-cred flag.
binary_properties BinaryProperties Executed binary properties. This field is only available on ProcessExec events.
user UserRecord UserRecord contains user information about the event. It is only supported when i) Tetragon is running as a systemd service or directly on the host, and ii) when the flag --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 of the process' owner.
gid google.protobuf.UInt32Value The real group ID of the process' owner.
euid google.protobuf.UInt32Value The effective user ID used for permission checks.
egid google.protobuf.UInt32Value The effective group ID used for permission checks.
suid google.protobuf.UInt32Value The saved user ID.
sgid google.protobuf.UInt32Value The saved group ID.
fsuid google.protobuf.UInt32Value the filesystem user ID used for filesystem access checks. Usually equals the euid.
fsgid google.protobuf.UInt32Value The filesystem group ID used for filesystem access checks. Usually equals the egid.
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 Label 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

ProcessLsm

Field Type Label Description
process Process
parent Process
function_name string LSM hook name.
policy_name string Name of the policy that created that LSM hook.
message string Short message of the Tracing Policy to inform users what is going on.
args KprobeArgument repeated Arguments definition of the observed LSM hook.
action KprobeAction Action performed when the LSM hook matched.
tags string repeated Tags of the Tracing Policy to categorize the event.
ima_hash string IMA file hash. Format algorithm:value.

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 Label 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.

SyscallId

Field Type Label Description
id uint32
abi string

Test

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

UserNamespace

Field Type Label 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 enforcer sensor.
KPROBE_ACTION_CLEANUPENFORCERNOTIFICATION 14 CleanupEnforcerNotification action cleanups any state left by NotifyEnforcer

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 Label 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
parent_binary_regex string repeated Filter parent process' binary using RE2 regular expression syntax.
cel_expression string repeated Filter using CEL expressions.
parent_arguments_regex string repeated Filter by process.parent.arguments field using RE2 regular expression syntax: https://github.com/google/re2/wiki/Syntax

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 Label 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
process_lsm ProcessLsm
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.
cluster_name string Name of the cluster where this event was observed.

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
PROCESS_LSM 28
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 Description
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
namespace string

DeleteTracingPolicyResponse

DisableSensorRequest

Field Type Label Description
name string

DisableSensorResponse

DisableTracingPolicyRequest

Field Type Label Description
name string
namespace string

DisableTracingPolicyResponse

DumpProcessCacheReqArgs

Field Type Label Description
skip_zero_refcnt bool
exclude_execve_map_processes bool

DumpProcessCacheResArgs

Field Type Label Description
processes ProcessInternal repeated

EnableSensorRequest

Field Type Label Description
name string

EnableSensorResponse

EnableTracingPolicyRequest

Field Type Label Description
name string
namespace string

EnableTracingPolicyResponse

GetDebugRequest

Field Type Label Description
flag ConfigFlag
dump DumpProcessCacheReqArgs

GetDebugResponse

Field Type Label Description
flag ConfigFlag
level LogLevel
processes DumpProcessCacheResArgs

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

ProcessInternal

Field Type Label Description
process Process
color string
refcnt google.protobuf.UInt32Value
refcnt_ops ProcessInternal.RefcntOpsEntry repeated refcnt_ops is a map of operations to refcnt change keys can be: - "process++": process increased refcnt (i.e. this process starts) - "process–": process decreased refcnt (i.e. this process exits) - "parent++": parent increased refcnt (i.e. a process starts that has this process as a parent) - "parent–": parent decreased refcnt (i.e. a process exits that has this process as a parent)

ProcessInternal.RefcntOpsEntry

Field Type Label Description
key string
value int32

RemoveSensorRequest

Field Type Label Description
name string

RemoveSensorResponse

SensorStatus

Field Type Label 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)

SetDebugRequest

Field Type Label Description
flag ConfigFlag
level LogLevel

SetDebugResponse

Field Type Label Description
flag ConfigFlag
level LogLevel

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
kernel_memory_bytes uint64 the amount of kernel memory in bytes used by policy's sensors non-shared BPF maps (memlock)

ConfigFlag

For now, we only want to support debug-related config flags to be configurable.

Name Number Description
CONFIG_FLAG_LOG_LEVEL 0
CONFIG_FLAG_DUMP_PROCESS_CACHE 1

LogLevel

Name Number Description
LOG_LEVEL_PANIC 0
LOG_LEVEL_FATAL 1
LOG_LEVEL_ERROR 2
LOG_LEVEL_WARN 3
LOG_LEVEL_INFO 4
LOG_LEVEL_DEBUG 5
LOG_LEVEL_TRACE 6

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
TP_STATE_LOADING 5 in the process of loading
TP_STATE_UNLOADING 6 in the process of unloading

FineGuidanceSensors

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

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_bpf_missed_events_total

Number of Tetragon perf events that are failed to be sent from the kernel.

label values
error E2BIG, EBUSY, EINVAL, ENOENT, ENOSPC, unknown
msg_op 13, 14, 15, 16, 23, 24, 25, 26, 27, 5, 7

tetragon_build_info

Build information about tetragon

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

tetragon_data_cache_capacity

The capacity of the data cache.

tetragon_data_cache_evictions_total

Number of data cache LRU evictions.

tetragon_data_cache_misses_total

Number of data cache misses.

label values
operation get, remove

tetragon_data_cache_size

The size of the data cache

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_enforcer_missed_notifications_total

The number of missed notifications by the enforcer.

label values
info syscall
policy policy-name
reason reason

tetragon_errors_total

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

label values
type event_finalize_process_info_failed, process_metadata_username_failed, process_metadata_username_ignored_not_in_host_namespaces, process_pid_tid_mismatch

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_LSM, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO

tetragon_event_cache_fetch_failures_total

Number of failed fetches from the event cache. These won’t be retried as they already exceeded the limit.

label values
entry_type parent_info, pod_info, process_info
event_type PROCESS_EXEC, PROCESS_EXIT, PROCESS_KPROBE, PROCESS_LOADER, PROCESS_LSM, PROCESS_THROTTLE, PROCESS_TRACEPOINT, PROCESS_UPROBE, RATE_LIMIT_INFO

tetragon_event_cache_fetch_retries_total

Number of retries when fetching info from the event cache.

label values
entry_type parent_info, pod_info, process_info

tetragon_event_cache_inserts_total

Number of inserts to the event cache.

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_events_missing_process_info_total

Number of events missing process info.

tetragon_export_ratelimit_events_dropped_total

Number of events dropped on export due to rate limiting

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, 13, 14, 15, 16, 23, 24, 25, 26, 27, 5, 7

tetragon_handling_latency

The latency of handling messages in us.

label values
op 13, 14, 15, 16, 23, 24, 25, 26, 27, 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

The total number of Tetragon probe missed by link.

label values
attach sys_panic
policy monitor_panic

tetragon_missed_prog_probes_total

The total number of Tetragon probe missed by program.

label values
attach sys_panic
policy monitor_panic

tetragon_msg_op_total

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

label values
msg_op 13, 14, 15, 16, 23, 24, 25, 26, 27, 5, 7

tetragon_notify_overflowed_events_total

The total number of events dropped because listener buffer was full

tetragon_observer_ringbuf_errors_total

Number of errors when reading Tetragon ring buffer.

tetragon_observer_ringbuf_events_lost_total

Number of perf events Tetragon ring buffer lost.

tetragon_observer_ringbuf_events_received_total

Number of perf events Tetragon ring buffer received.

tetragon_observer_ringbuf_queue_events_lost_total

Number of perf events Tetragon ring buffer events queue lost.

tetragon_observer_ringbuf_queue_events_received_total

Number of perf events Tetragon ring buffer events queue received.

tetragon_overhead_program_runs_total

The total number of times BPF program was executed.

label values
attach sys_open
policy enforce
policy_namespace ns
section kprobe/sys_open
sensor generic_kprobe

tetragon_overhead_program_seconds_total

The total time of BPF program running.

label values
attach sys_open
policy enforce
policy_namespace ns
section kprobe/sys_open
sensor generic_kprobe

tetragon_policyfilter_hook_container_name_missing_total

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

tetragon_policyfilter_operations_total

Number of policy filter operations.

label values
error generic-error, pod-namespace-conflict
operation 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_evictions_total

Number of process cache LRU evictions.

tetragon_process_cache_misses_total

Number of process cache misses.

label values
operation get, remove

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_tracingpolicy_kernel_memory_bytes

The amount of kernel memory in bytes used by policy’s sensors non-shared BPF maps (memlock).

label values
policy example-tracingpolicy
policy_namespace example-namespace

tetragon_tracingpolicy_loaded

The number of loaded tracing policy by state.

label values
state disabled, enabled, error, load_error

tetragon_watcher_delete_pod_cache_hits

The total hits for pod information in the deleted pod cache.

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 wall-time pause (stop-the-world) duration in garbage collection cycles.

go_gc_gogc_percent

Heap size target percentage configured by the user, otherwise 100. This value is set by the GOGC environment variable, and the runtime/debug.SetGCPercent function. Sourced from /gc/gogc:percent

go_gc_gomemlimit_bytes

Go runtime memory limit configured by the user, otherwise math.MaxInt64. This value is set by the GOMEMLIMIT environment variable, and the runtime/debug.SetMemoryLimit function. Sourced from /gc/gomemlimit:bytes

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 in heap and currently in use. Equals to /memory/classes/heap/objects:bytes.

go_memstats_alloc_bytes_total

Total number of bytes allocated in heap until now, even if released already. Equals to /gc/heap/allocs:bytes.

go_memstats_buck_hash_sys_bytes

Number of bytes used by the profiling bucket hash table. Equals to /memory/classes/profiling/buckets:bytes.

go_memstats_frees_total

Total number of heap objects frees. Equals to /gc/heap/frees:objects + /gc/heap/tiny/allocs:objects.

go_memstats_gc_sys_bytes

Number of bytes used for garbage collection system metadata. Equals to /memory/classes/metadata/other:bytes.

go_memstats_heap_alloc_bytes

Number of heap bytes allocated and currently in use, same as go_memstats_alloc_bytes. Equals to /memory/classes/heap/objects:bytes.

go_memstats_heap_idle_bytes

Number of heap bytes waiting to be used. Equals to /memory/classes/heap/released:bytes + /memory/classes/heap/free:bytes.

go_memstats_heap_inuse_bytes

Number of heap bytes that are in use. Equals to /memory/classes/heap/objects:bytes + /memory/classes/heap/unused:bytes

go_memstats_heap_objects

Number of currently allocated objects. Equals to /gc/heap/objects:objects.

go_memstats_heap_released_bytes

Number of heap bytes released to OS. Equals to /memory/classes/heap/released:bytes.

go_memstats_heap_sys_bytes

Number of heap bytes obtained from system. Equals to /memory/classes/heap/objects:bytes + /memory/classes/heap/unused:bytes + /memory/classes/heap/released:bytes + /memory/classes/heap/free:bytes.

go_memstats_last_gc_time_seconds

Number of seconds since 1970 of last garbage collection.

go_memstats_mallocs_total

Total number of heap objects allocated, both live and gc-ed. Semantically a counter version for go_memstats_heap_objects gauge. Equals to /gc/heap/allocs:objects + /gc/heap/tiny/allocs:objects.

go_memstats_mcache_inuse_bytes

Number of bytes in use by mcache structures. Equals to /memory/classes/metadata/mcache/inuse:bytes.

go_memstats_mcache_sys_bytes

Number of bytes used for mcache structures obtained from system. Equals to /memory/classes/metadata/mcache/inuse:bytes + /memory/classes/metadata/mcache/free:bytes.

go_memstats_mspan_inuse_bytes

Number of bytes in use by mspan structures. Equals to /memory/classes/metadata/mspan/inuse:bytes.

go_memstats_mspan_sys_bytes

Number of bytes used for mspan structures obtained from system. Equals to /memory/classes/metadata/mspan/inuse:bytes + /memory/classes/metadata/mspan/free:bytes.

go_memstats_next_gc_bytes

Number of heap bytes when next garbage collection will take place. Equals to /gc/heap/goal:bytes.

go_memstats_other_sys_bytes

Number of bytes used for other system allocations. Equals to /memory/classes/other:bytes.

go_memstats_stack_inuse_bytes

Number of bytes obtained from system for stack allocator in non-CGO environments. Equals to /memory/classes/heap/stacks:bytes.

go_memstats_stack_sys_bytes

Number of bytes obtained from system for stack allocator. Equals to /memory/classes/heap/stacks:bytes + /memory/classes/os-stacks:bytes.

go_memstats_sys_bytes

Number of bytes obtained from system. Equals to /memory/classes/total:byte.

go_sched_gomaxprocs_threads

The current runtime.GOMAXPROCS setting, or the number of operating system threads that can execute user-level Go code simultaneously. Sourced from /sched/gomaxprocs:threads

go_sched_latencies_seconds

Distribution of the time goroutines have spent in the scheduler in a runnable state before actually running. Bucket counts increase monotonically. Sourced from /sched/latencies:seconds

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_network_receive_bytes_total

Number of bytes received by the process over the network.

process_network_transmit_bytes_total

Number of bytes sent by the process over the network.

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_LSM, 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