Tetragon Files

Upgrade notes

Read the upgrade notes carefully before upgrading Tetragon. Depending on your setup, changes listed here might require a manual intervention.

• Enabling ancestors for process events is now configured by a new --enable-ancestors flag. The following flags are being deprecarted in this (1.5) and are scheduled for removal in the next (1.6):
• --enable-process-ancestors
• --enable-process-kprobe-ancestors
• --enable-process-tracepoint-ancestors
• --enable-process-uprobe-ancestors

• --enable-process-lsm-ancestors

• The logging library used by Tetragon is migrated from logrus to log/slog. This change is not expected to affect the end user, but it may require some adjustments in custom scripts or tools that parse Tetragon logs.

• level=warning is now level=warn

Helm Values

• The default value of metrics scrape interval in both agent and operator ServiceMonitors (tetragon.prometheus.serviceMonitor.scrapeInterval and tetragonOperator.prometheus.serviceMonitor.scrapeInterval values respectively) is changed from 10s to 60s.

• OciHookSetup section is removed after being deprecated in 1.2.

Changes from v1.4.1 to v1.5.0

total: 391 commits, prs: 182 pr commits: 390

Major Changes

• tetragon/windows: Support Windows create and exit process - observer changes (https://github.com/cilium/tetragon/pull/3577) by @ExceptionalHandler
• tetragon/windows: Support Windows create and exit process - sensor changes (https://github.com/cilium/tetragon/pull/3578) by @ExceptionalHandler
• tetragon/Windows: Add support for process create and exit - ring-buffer (https://github.com/cilium/tetragon/pull/3591) by @ExceptionalHandler
• tetragon/windows: Port tetragon on Windows - cmd/tetragon/main.go (https://github.com/cilium/tetragon/pull/3592) by @ExceptionalHandler

Bugfixes

• helm: fix extraHookargs in rthooks (https://github.com/cilium/tetragon/pull/3566) by @kkourt
• Fix event source pod attribution when env var HUBBLE_NODE_NAME is set (https://github.com/cilium/tetragon/pull/3609) by @odinuge
• fix(chart): correct operator securityContext values (https://github.com/cilium/tetragon/pull/3681) by @JefeDavis
• tracingpolicy: fix issue in argument order with the resolve argument option (https://github.com/cilium/tetragon/pull/3737) by @kkourt
• Fix an issue where inInitTree was not properly accounting processes started before Tetragon. (https://github.com/cilium/tetragon/pull/3827) by @will-isovalent
• tracinpolicy: respect syscall attribute in lists (https://github.com/cilium/tetragon/pull/3895) by @kkourt
• Fixes load sensor failure when mixing rate limited and non rate limited kprobes. (https://github.com/cilium/tetragon/pull/3903) by @mtardy
• bpf: fix issue with multiple inactive selectors (https://github.com/cilium/tetragon/pull/3947) by @kkourt

Minor Changes

• tetragon/windows: Compilation only change to build config package (https://github.com/cilium/tetragon/pull/3537) by @ExceptionalHandler
• tetragon/windows: Port reader/namespace package to Windows (https://github.com/cilium/tetragon/pull/3548) by @ExceptionalHandler
• tetragon/windows: Port package errmetrics to Windows (https://github.com/cilium/tetragon/pull/3534) by @ExceptionalHandler
• tetragon/windows: Compilation only change for pkg/metrics/syscallmetrics (https://github.com/cilium/tetragon/pull/3530) by @ExceptionalHandler
• tetragon/windows: Port pkg/kernels to Windows (https://github.com/cilium/tetragon/pull/3529) by @ExceptionalHandler
• tetragon/windows: Compilation only change to compile cgroups package (https://github.com/cilium/tetragon/pull/3536) by @ExceptionalHandler
• tetragon/windows: Port pidfile package on Windows (https://github.com/cilium/tetragon/pull/3532) by @ExceptionalHandler
• tetragon/windows: Compilation only Change for pkg/procsyms on Windows (https://github.com/cilium/tetragon/pull/3533) by @ExceptionalHandler
• Windows: Build tetragon on Windows (Part -2) (https://github.com/cilium/tetragon/pull/3488) by @ExceptionalHandler
• tetragon/windows: Compilation only change for pkg/metricconfig package on Windows (https://github.com/cilium/tetragon/pull/3531) by @ExceptionalHandler
• tetragon: add support for path offload (https://github.com/cilium/tetragon/pull/3480) by @olsajiri
• tetragon/windows: port package sensors/exec/procevents into Windows (https://github.com/cilium/tetragon/pull/3561) by @ExceptionalHandler
• tetragon/windows: Compilation change to build testutils (https://github.com/cilium/tetragon/pull/3539) by @ExceptionalHandler
• tetragon/windows: Add default definitions for Windows (https://github.com/cilium/tetragon/pull/3538) by @ExceptionalHandler
• tetragon/widows: Add signal translation for Windows (https://github.com/cilium/tetragon/pull/3547) by @ExceptionalHandler
• tetragon/windows: Port bpf package into Windows (https://github.com/cilium/tetragon/pull/3563) by @ExceptionalHandler
• tetragon/windows: Port cmd/tetra binary into Windows (https://github.com/cilium/tetragon/pull/3573) by @ExceptionalHandler
• tetragon: rhel7 changes (https://github.com/cilium/tetragon/pull/3574) by @olsajiri
• tetragon: fix path permissions (https://github.com/cilium/tetragon/pull/3599) by @olsajiri
• Enhance Tetragon Events with Pod Annotations Support (https://github.com/cilium/tetragon/pull/3527) by @cy83rc0llect0r
• tetragon: add raw tracepoints (https://github.com/cilium/tetragon/pull/3558) by @olsajiri
• PodInfo: Add .process.pod.container.privileged field (https://github.com/cilium/tetragon/pull/3661) by @tpapagian
• helm: Change default metrics scrape interval to 60s (https://github.com/cilium/tetragon/pull/3675) by @ghost
• k8s: Remove the logic to handle v1beta1 CRDs (https://github.com/cilium/tetragon/pull/3677) by @michi-covalent
• tetragon: Allow uprobes to use actions (https://github.com/cilium/tetragon/pull/3676) by @olsajiri
• tetragon: Fix check_cap tester program call (https://github.com/cilium/tetragon/pull/3688) by @olsajiri
• helm: remove deprecated ociHookSetup section (https://github.com/cilium/tetragon/pull/3704) by @kkourt
• policyfilter: Add support for repo key in containerSelector (https://github.com/cilium/tetragon/pull/3709) by @tpapagian
• tetragon/windows: Fix observer to make it event independent (https://github.com/cilium/tetragon/pull/3716) by @ExceptionalHandler
• tracingpolicy: support IPv4-mapped IPv6 address form in selectors. (https://github.com/cilium/tetragon/pull/3714) by @kobrineli
• tetragon: Fix kprobe argument printers order (https://github.com/cilium/tetragon/pull/3725) by @olsajiri
• tetragon: Move some event_config values to arrays (https://github.com/cilium/tetragon/pull/3738) by @olsajiri
• tetragon: allow to define uprobe with offset and ref_ctr_offset (https://github.com/cilium/tetragon/pull/3695) by @olsajiri
• Tetragon events now contain Kubernetes node labels. (https://github.com/cilium/tetragon/pull/3759) by @michi-covalent
• tetragon: Remove superficial program.MapLoad.Index (https://github.com/cilium/tetragon/pull/3756) by @olsajiri
• tetragon: Deprecate enable-process-ancestors boolean flags (https://github.com/cilium/tetragon/pull/3581) by @t0x01
• tetragon: assorted fixes (https://github.com/cilium/tetragon/pull/3804) by @olsajiri
• tetragon: do proper cleanup for uprobe and tracepoint sensors (https://github.com/cilium/tetragon/pull/3822) by @olsajiri
• tracingpolicy: allow to ignore kprobes for calls that cannot be found (https://github.com/cilium/tetragon/pull/3825) by @kkourt
• logging: Migrate from logrus to slog (https://github.com/cilium/tetragon/pull/3814) by @sayboras
• tetragon/windows: Support multiple programs from a single collection (https://github.com/cilium/tetragon/pull/3832) by @ExceptionalHandler
• RFC tetragon: Do not rate limit exit events (https://github.com/cilium/tetragon/pull/3842) by @olsajiri
• tetragon: assorted fixes (https://github.com/cilium/tetragon/pull/3846) by @olsajiri
• tetragon/windows: Add bind program type GUID (https://github.com/cilium/tetragon/pull/3851) by @ExceptionalHandler
• sensor: reduce logs in loading/unloading (https://github.com/cilium/tetragon/pull/3853) by @kkourt
• tetragon: factor args processing (https://github.com/cilium/tetragon/pull/3730) by @olsajiri
• tetragon: matchBinaries followChildren fixes (https://github.com/cilium/tetragon/pull/3821) by @olsajiri
• tetragon: Add macros for atomic instructions (https://github.com/cilium/tetragon/pull/3869) by @olsajiri
• tracingpolicies: add CapabiliitesGained operator (https://github.com/cilium/tetragon/pull/3887) by @kkourt
• helm: add tetragon.nameOverride and tetragonOperator.nameOverride (https://github.com/cilium/tetragon/pull/3864) by @slntopp
• bugtool: Collect pprof CPU profile (https://github.com/cilium/tetragon/pull/3916) by @michi-covalent
• tetragon: add support to follow children of old process (https://github.com/cilium/tetragon/pull/3901) by @olsajiri
• tracingpolicy: return error on unsupported number of values (https://github.com/cilium/tetragon/pull/3934) by @kkourt

CI Changes

• e2e: port forwarding fixes (https://github.com/cilium/tetragon/pull/3555) by @kkourt
• ci: In "Tetragon Go Test" add vmlinux in artifact when test fails (https://github.com/cilium/tetragon/pull/3526) by @tdaudi
• Revert "renovate: add v1.2 for golang 1.23" (https://github.com/cilium/tetragon/pull/3598) by @mtardy
• Update golangci-lint to v2 and fix newly discovered issues in the code base (https://github.com/cilium/tetragon/pull/3607) by @mtardy
• linters: take the golangci-lint v2 bump opportunity to enable more linters (https://github.com/cilium/tetragon/pull/3608) by @mtardy
• tetragon/windows: Add windows compile as a ci step (https://github.com/cilium/tetragon/pull/3611) by @ExceptionalHandler
• tetragon/windows: Run unit tests on Windows (https://github.com/cilium/tetragon/pull/3637) by @ExceptionalHandler
• tetragon/windows: Build windows bpf program and smoke test tetragon (https://github.com/cilium/tetragon/pull/3645) by @ExceptionalHandler
• ci: running golangci-lint on windows (https://github.com/cilium/tetragon/pull/3565) by @mtardy
• policyfilter/e2e: Fix e2e tests (https://github.com/cilium/tetragon/pull/3733) by @tpapagian
• tetragon/windows: CI Fix attempt by adding -Wait switch in racy steps (https://github.com/cilium/tetragon/pull/3736) by @ExceptionalHandler
• vmtests CI: avoid running duplicate tests (https://github.com/cilium/tetragon/pull/3694) by @kkourt
• e2e: Don't install Cilium (https://github.com/cilium/tetragon/pull/3815) by @michi-covalent
• e2e: Capture Tetragon state on failure (https://github.com/cilium/tetragon/pull/3812) by @michi-covalent
• e2e: Make uninstalling Tetragon optional (https://github.com/cilium/tetragon/pull/3835) by @michi-covalent
• e2e/tests: Make WaitForTracingPolicy configurable (https://github.com/cilium/tetragon/pull/3858) by @tpapagian
• Fix CI (https://github.com/cilium/tetragon/pull/3874) by @ExceptionalHandler
• CI: Push OCI Helm chart (https://github.com/cilium/tetragon/pull/3915) by @michi-covalent

Documentation changes

• feat: replace community X link (https://github.com/cilium/tetragon/pull/3606) by @yasell
• feat: develop Tetragon Use Cases pages (https://github.com/cilium/tetragon/pull/3277) by @annaindistress
• doc: update export filtering example (https://github.com/cilium/tetragon/pull/3626) by @yeongjukang
• doc: add events.proto link for event filters (https://github.com/cilium/tetragon/pull/3641) by @yeongjukang
• docs: improve features pages copy (https://github.com/cilium/tetragon/pull/3640) by @paularah
• examples: use explicit wording about guarantees (https://github.com/cilium/tetragon/pull/3663) by @kkourt
• doc: fix policy-library sshd anchor link & title (https://github.com/cilium/tetragon/pull/3678) by @tico88612
• docs: update rthooks installation (https://github.com/cilium/tetragon/pull/3684) by @kkourt
• doc: fix cgroup rate explanation not match the parameter (https://github.com/cilium/tetragon/pull/3699) by @tico88612
• doc: fix some links in documentation (https://github.com/cilium/tetragon/pull/3642) by @MickaelFontes
• docs: update homepage announcement section (https://github.com/cilium/tetragon/pull/3673) by @paularah
• docs: Replace example file for matchCapabilityChanges (https://github.com/cilium/tetragon/pull/3790) by @sayboras
• Update selectors.md (https://github.com/cilium/tetragon/pull/3796) by @itsCheithanya
• docs: add video of KubeCon Japan 2025 (https://github.com/cilium/tetragon/pull/3860) by @yukinakanaka
• fix "security_inode_copy_up" example in docs (https://github.com/cilium/tetragon/pull/3870) by @simsor
• docs: Clarify that export filters (denylist/allowlist) only apply to JSON file exports, not gRPC streaming (https://github.com/cilium/tetragon/pull/3888) by @f4r00q
• docs: add instruction to cleanup getting started network policy (https://github.com/cilium/tetragon/pull/3904) by @mtardy

Dependency updates

• chore(deps): update renovatebot/github-action action to v42 (main) (https://github.com/cilium/tetragon/pull/3754) by @cilium-renovate[bot]
• deps: update controller-tools to v0.18.0 and k8s to v0.33.0 (https://github.com/cilium/tetragon/pull/3768) by @mtardy
• update cilium/ebpf to v0.19.0 (https://github.com/cilium/tetragon/pull/3849) by @lmb

Misc Changes

• Prepare for v1.4.1 release (https://github.com/cilium/tetragon/pull/3893) by @mtardy
• Remove LoadBtf() and add test wrapper for single btf use (https://github.com/cilium/tetragon/pull/3414) by @tdaudi
• Starting v1.5 development (https://github.com/cilium/tetragon/pull/3549) by @kkourt
• tetragon/windows: Use a package-level 'not supported' error variable (https://github.com/cilium/tetragon/pull/3562) by @ExceptionalHandler
• tetragon/windows: Build reader/path and reader/network packages on Windows (https://github.com/cilium/tetragon/pull/3559) by @ExceptionalHandler
• tetragon/windows: Port reader/proc package on Windows (https://github.com/cilium/tetragon/pull/3560) by @ExceptionalHandler
• tetragon/windows: Port process cache package on Windows (https://github.com/cilium/tetragon/pull/3575) by @ExceptionalHandler
• podinfo: Add spec.nodeName field (https://github.com/cilium/tetragon/pull/3580) by @michi-covalent
• watcher: Watch namespaces (https://github.com/cilium/tetragon/pull/3603) by @michi-covalent
• tetragon/windows: The process monitor bpf program (https://github.com/cilium/tetragon/pull/3579) by @ExceptionalHandler
• Restore proc_test.go files (https://github.com/cilium/tetragon/pull/3616) by @ExceptionalHandler
• tetragon/windows: Port Unit Tests in cmd/tetragon on Windows (https://github.com/cilium/tetragon/pull/3618) by @ExceptionalHandler
• tetragon/windows: Exclude vmtests unit tests from being compiled on Windows (https://github.com/cilium/tetragon/pull/3619) by @ExceptionalHandler
• tetragon/windows: Exclude some unit tests for Windows (https://github.com/cilium/tetragon/pull/3620) by @ExceptionalHandler
• tetragon/windows: Port reader unit tests into Windows (https://github.com/cilium/tetragon/pull/3622) by @ExceptionalHandler
• tetragon/windows: Port unit tests in grpc package into Windows (https://github.com/cilium/tetragon/pull/3621) by @ExceptionalHandler
• tetragon/windows: Fix some logging in ringbuf and exec observer implementations (https://github.com/cilium/tetragon/pull/3623) by @ExceptionalHandler
• go.mod: Consistently add replace directives (https://github.com/cilium/tetragon/pull/3638) by @michi-covalent
• observertesthelper: Remove unused crd option (https://github.com/cilium/tetragon/pull/3650) by @michi-covalent
• Refactor Pod watcher (https://github.com/cilium/tetragon/pull/3652) by @michi-covalent
• Use controller-runtime manager to access namespaces (https://github.com/cilium/tetragon/pull/3643) by @michi-covalent
• Get tracing policy informers from controller-runtime manager (https://github.com/cilium/tetragon/pull/3651) by @michi-covalent
• Fix / clean up repo-docker-run.sh (https://github.com/cilium/tetragon/pull/3654) by @michi-covalent
• GetCgroupIdFromPath: add path to error (https://github.com/cilium/tetragon/pull/3666) by @kkourt
• Refactor waitCRDs function (https://github.com/cilium/tetragon/pull/3657) by @michi-covalent
• buf (codegen) fixes (https://github.com/cilium/tetragon/pull/3683) by @kkourt
• fix(deps): Remove metallb dependency (https://github.com/cilium/tetragon/pull/3686) by @joestringer
• k8s: Let controller-runtime manage the pod informer (https://github.com/cilium/tetragon/pull/3679) by @michi-covalent
• sensors: cache spec when loading maps (https://github.com/cilium/tetragon/pull/3685) by @kkourt
• loaderCache: copy map spec before using it (https://github.com/cilium/tetragon/pull/3693) by @kkourt
• watcher: Remove unused AddPodInformer function (https://github.com/cilium/tetragon/pull/3690) by @michi-covalent
• test: Remove duplicate fake k8s watcher (https://github.com/cilium/tetragon/pull/3689) by @michi-covalent
• watcher / k8s cleanup (https://github.com/cilium/tetragon/pull/3696) by @michi-covalent
• Feature pages nits (https://github.com/cilium/tetragon/pull/3713) by @xmulligan
• crdutils: Move test helpers to dedicated file and export them (https://github.com/cilium/tetragon/pull/3723) by @ghost
• Temporarily disable controller-runtime metrics (https://github.com/cilium/tetragon/pull/3740) by @michi-covalent
• tetragon/windows: Add Multiple program attach types (https://github.com/cilium/tetragon/pull/3735) by @ExceptionalHandler
• reduce image size by compressing bpf objs (https://github.com/cilium/tetragon/pull/3747) by @kkourt
• tetragon/windows: Fix exec/exit event timestamp in event json (https://github.com/cilium/tetragon/pull/3748) by @ExceptionalHandler
• Fix "not addr" filters across address families (https://github.com/cilium/tetragon/pull/3758) by @kevsecurity
• Sensors: Use require over assert in tests (https://github.com/cilium/tetragon/pull/3760) by @kevsecurity
• deps: Remove cilium hubble package dependency (https://github.com/cilium/tetragon/pull/3764) by @sayboras
• pkg/k8s: generate deepcopy function on k8s types (https://github.com/cilium/tetragon/pull/3765) by @mtardy
• deps: Remove Cilium slim k8s package (https://github.com/cilium/tetragon/pull/3766) by @sayboras
• linters: enable testifylints and fix issues (https://github.com/cilium/tetragon/pull/3769) by @mtardy
• deps: Remove all cilium/cilium package dependency (https://github.com/cilium/tetragon/pull/3767) by @sayboras
• refactor: Rename functions in the node package (https://github.com/cilium/tetragon/pull/3786) by @michi-covalent
• btf: Use user-provided KernelTypes if the btfSpec is nil (https://github.com/cilium/tetragon/pull/3773) by @tpapagian
• tetragon/windows: add uid to exec events in Windows (https://github.com/cilium/tetragon/pull/3785) by @ExceptionalHandler
• Do proper cleanup on maps during sensor unload (https://github.com/cilium/tetragon/pull/3798) by @tpapagian
• tools: Avoid picking protoc file randomly (https://github.com/cilium/tetragon/pull/3823) by @sayboras
• helm: fix typo in metricsLabelFilter comment (https://github.com/cilium/tetragon/pull/3824) by @tklauser
• Tracing: Convert network tests to test suite (https://github.com/cilium/tetragon/pull/3830) by @kevsecurity
• Use Go 1.19 atomic types (https://github.com/cilium/tetragon/pull/3833) by @tklauser
• confmap: use config.FindProgramFile() (https://github.com/cilium/tetragon/pull/3834) by @kkourt
• make gen_compile_commands for tetragon (https://github.com/cilium/tetragon/pull/3698) by @0xMALVEE
• tetra: export common.RetryPolicy methods (https://github.com/cilium/tetragon/pull/3847) by @mtardy
• fix mask issue for capability types (https://github.com/cilium/tetragon/pull/3852) by @kkourt
• btf: skip arg validation if resolve is set (https://github.com/cilium/tetragon/pull/3848) by @kkourt
• tetragon/windows: Add sockops attach type GUID to windows loader (https://github.com/cilium/tetragon/pull/3859) by @ExceptionalHandler
• tetragon/windows: Fix ancestor list (https://github.com/cilium/tetragon/pull/3863) by @ExceptionalHandler
• BTF validation updates (https://github.com/cilium/tetragon/pull/3868) by @kkourt
• cel: Move heavy operations outside of loops (https://github.com/cilium/tetragon/pull/3871) by @tpapagian
• cel: Apply EvalCEL only on events that are related to the rule (https://github.com/cilium/tetragon/pull/3875) by @tpapagian
• Improve error messages from reading kallsyms. (https://github.com/cilium/tetragon/pull/3891) by @mtardy
• Explain why LSM attach might fail on arm64 <6.0 kernels. (https://github.com/cilium/tetragon/pull/3894) by @mtardy
• github: update issue template to use issue types (https://github.com/cilium/tetragon/pull/3902) by @mtardy
• move ExecveMapUpdater to its own package (https://github.com/cilium/tetragon/pull/3907) by @kkourt
• cel: Remove memory allocation on every event (https://github.com/cilium/tetragon/pull/3876) by @tpapagian
• refactor: Clean up composite literals and nil comparisons (https://github.com/cilium/tetragon/pull/3918) by @yeongjukang
• helm: add action on tetragon servicemonitor (https://github.com/cilium/tetragon/pull/3908) by @HujinoKun
• contrib: Update gitignore (https://github.com/cilium/tetragon/pull/3927) by @tpapagian
• btf validation fixes (https://github.com/cilium/tetragon/pull/3929) by @kkourt
• feat(helm): add icon section on Chart.yaml file (https://github.com/cilium/tetragon/pull/3930) by @HujinoKun
• chore(helm): bump helm chart version (https://github.com/cilium/tetragon/pull/3936) by @HujinoKun
• tetragon: Forgotten leftover for v6.12 variant (https://github.com/cilium/tetragon/pull/3937) by @olsajiri
• bpf: Use bpf_ktime_get_boot_ns when available (https://github.com/cilium/tetragon/pull/3938) by @tpapagian
• fix: Force remove tetragon-clang container for the tetragon-bpf target in case it's still running. (https://github.com/cilium/tetragon/pull/3935) by @acamatcisco
• Prepare for v1.5.0 release (https://github.com/cilium/tetragon/pull/3950) by @tpapagian