# Cilium Tetragon: eBPF Runtime Security Observability and Enforcement

> Tetragon watches process execution, syscalls and file or network access from the kernel, and can kill a process when a policy matches. It is a serious tool with a narrow fit: Linux and Kubernetes, kernel-version dependent, with the enforcement path carrying real blast radius.

**cilium/tetragon** — eBPF-based Security Observability and Runtime Enforcement. Cilium’s new Tetragon component enables powerful real-time, eBPF-based Security Observability and Runtime Enforcement.

- Repository: https://github.com/cilium/tetragon
- Website: https://tetragon.io
- Stars: 5,036 · Forks: 615
- Language: C
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/cilium-tetragon

## What Tetragon solves for Kubernetes and Linux operators

Most container security tooling observes from outside the workload: it reads audit logs, watches the container runtime API, or samples the filesystem. That leaves gaps. A process that execs inside a container, opens a credential file, and exits in under a second may never appear in a runtime log at the right granularity, and by the time a scanner sees the image the process is gone.

Tetragon takes the other position. The README describes it as "eBPF-based Security Observability and Runtime Enforcement" and lists what it detects: process execution events, system call activity, and I/O activity including network and file access. The events are generated in the kernel and enriched with Linux and Kubernetes metadata, so a process_exec event carries the namespace and pod it belongs to rather than a bare PID.

That matters for a specific audience. Platform and security engineers running multi-tenant Kubernetes clusters, who need to answer "what actually ran in this pod" and "did anything touch this file", are the primary users. The second group is anyone who wants to react in-kernel rather than after the fact, because Tetragon does not stop at detection. The USERS.md file in the repository lists organizations deploying it, which is the place to look if you want to know whether your situation resembles someone else's.

## How Tetragon hooks the kernel and enriches events

The repository layout tells you where the work happens. bpf/ holds the eBPF programs, pkg/ holds the Go agent, api/ holds the protobuf definitions the agent serves, cmd/ holds the binaries, and operator/ holds the Kubernetes operator. The Dockerfile shows the build split into stages: a clang image compiles the BPF objects, a Go image then builds the tetragon and tetra binaries, and the BPF objects are optionally gzipped before being embedded.

The event model has two layers. Process lifecycle events, process_exec and process_exit, are generated by default according to the README, which means you get full process lifecycle observability without writing a policy. Above that sits generic tracing: process_kprobe, process_tracepoint and process_uprobe events, driven by a TracingPolicy. A TracingPolicy is the unit of configuration. It names a kernel hook (a kprobe on a function, a tracepoint, a uprobe in a userspace binary) and a CEL expression that decides whether to emit an event or take an action. The dependency list confirms this: github.com/google/cel-go is in go.mod, and so is github.com/cilium/ebpf, the library that loads the programs.

The data flow is: eBPF program runs at the hook, filters or enriches in kernel space, pushes an event up to the agent. The agent attaches Kubernetes identity and serves the result over gRPC (google.golang.org/grpc is in go.mod, and there is a Prometheus middleware dependency for metrics). The tetra CLI is a gRPC client. That is the whole architecture in one line, and it explains a practical constraint: the agent is the chokepoint. If it falls behind, events queue or drop, and no policy will save you.

## Installing Tetragon and running a first policy

The README does not inline install commands. It points to the official documentation at tetragon.io, and specifically to the getting started guides for Kubernetes and for Linux with Docker, the deployment guide, and the tetra CLI install page. For Kubernetes the chart lives under install/, and the operator under operator/ manages the agent lifecycle. Because no literal install command appears in the README, go to the install-k8s guide and use the values documented there.

The agent runs as a DaemonSet, so one pod per node. Once it is up, the default process_exec stream is already flowing. The tetra CLI is the client, built by the same Makefile targets as the agent; the Makefile declares the tetragon and tetra targets that the Dockerfile invokes with:

```dockerfile
RUN --mount=type=cache,target=/go/pkg/mod \ 
    --mount=type=cache,target=/root/.cache/go-build \
    make VERSION=$TETRAGON_VERSION TARGET_ARCH=$TARGETARCH tetragon tetra
```

To watch events, use the CLI against the agent. The examples/ directory in the repository is the best reference for real policy shapes, with subdirectories for tracingpolicy, policylibrary, eventchecker and configuration. The exact field names and available hooks are documented on the TracingPolicy concept page, so read that page before writing a manifest rather than guessing at the schema.

What you should see once a policy is loaded is one event per matched hook, carrying the process, the Kubernetes pod identity, and the arguments the policy asked for. If the stream is empty, the two usual causes are that the hook name does not exist on your kernel or that the policy failed to load; the agent logs the load error, and that log is the first place to look.

## Where Tetragon is the wrong tool

Tetragon is Linux-only and kernel-dependent, and that is not a footnote. eBPF programs attach to hooks that exist in specific kernel versions with specific BTF and helper support. The repository ships a Dockerfile.clang and a pinned clang image, which tells you the BPF side is sensitive to toolchain versions. If you operate a fleet with a wide kernel spread, you will spend real time on which nodes can run which policies, and some nodes will simply not support a given hook. The project does not claim otherwise.

Enforcement is the sharper edge. Tetragon can react to events, and a reaction that kills a process is a production incident if the policy is wrong. The documentation covers enforcement, but the README does not document rollback of an enforcement action once taken, and it does not document a dry-run mode for policies. If your team's habit is to ship a policy and see what happens, this is the wrong tool for that habit. Observability first, with the event stream reviewed for false positives, is the only defensible sequence, and even then you need to be able to remove a policy quickly.

Volume is the third limit. Generating process_exec and process_exit by default means every exec on every node produces an event. On a busy cluster that is a lot of data, and the agent is a single process per node. Tetragon is not a log aggregation system and does not pretend to be one; you still need somewhere for the events to go and a way to query them. Teams expecting a self-contained SIEM will be disappointed.

## Tetragon compared with Falco and with Cilium itself

The obvious comparison is Falco. Both watch syscalls and both can alert on suspicious process behavior, but the mechanism differs. Falco's classic mode uses a kernel module or a probe plus a rule language evaluated largely in userspace, with rules written in a YAML-ish DSL. Tetragon pushes filtering and enrichment into eBPF programs and expresses match conditions in CEL. The practical consequence is that Tetragon's filtering happens closer to the hook, so you can drop events in kernel space before they reach the agent, while Falco's rule engine sees more of the stream. Tetragon's CEL expressions are also a different mental model from Falco's macro and list syntax; neither is obviously easier, and the choice often comes down to which one your team has already written rules in.

The second comparison is with Cilium itself, since Tetragon is described as Cilium's component. Cilium's core is network policy and connectivity, enforced on the network path. Tetragon works at the process and syscall layer. They overlap on network observability, and the README lists a network observability use case, but Cilium will not tell you which binary opened /etc/shadow and Tetragon will not route your pod traffic. Running both is normal; treating one as a replacement for the other is a mistake.

## Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-25, the same date as the v1.7.1 release. The release cadence visible in the repository is roughly quarterly for minor versions: v1.6.1 on 2026-03-31, v1.7.0 on 2026-04-29, v1.7.1 on 2026-08-25. That is a maintained project by the evidence available, and the pinned toolchain in the Dockerfile and Makefile suggests the maintainers care about reproducible builds.

Upgrade cost is dominated by the kernel interface, not by the Go code. Because BPF objects are compiled against a specific clang and loaded against a specific kernel, an agent upgrade can change which hooks are available or how events are shaped. The agent and the tetra CLI speak gRPC over the api/ protobuf definitions, so a CLI that is older than the agent can fail to parse new fields. Keep them in step. The operator under operator/ handles the DaemonSet rollout, but it cannot validate your TracingPolicies against the new agent's hook set for you.

Licensing: the repository is Apache-2.0. The README badges also reference BSD-2-Clause and GPL-2.0, which reflects that the eBPF programs and some vendored components carry different terms than the Go agent. If you redistribute Tetragon or embed it in a product, read LICENSE and the per-directory headers rather than assuming the top-level identifier covers everything. That is a statement about what the files show, not legal advice.

## Conclusion

Adopt Tetragon if you run Kubernetes on modern Linux kernels and need kernel-level visibility into process execution, file access and network activity with the option to enforce. Skip it if you need Windows or macOS coverage, if you cannot control kernel versions, or if you want a policy engine that is easy to reason about without reading eBPF internals. Verify first that your kernel exposes the hooks your TracingPolicy needs, that you have a plan for the volume of process_exec events before you turn on enforcement, and that the tetra CLI version matches the deployed agent version.

## FAQ

### What is Cilium Tetragon?

It is Cilium's eBPF-based security observability and runtime enforcement component. It detects process execution events, system call activity, and I/O activity including network and file access, and it is Kubernetes-aware so detection can be configured per workload.

### How does Tetragon work?

It attaches eBPF programs to kernel hooks and generates events enriched with Linux and Kubernetes metadata. Process lifecycle events (process_exec and process_exit) are produced by default, while process_kprobe, process_tracepoint and process_uprobe events come from TracingPolicies. The agent serves events over gRPC and the tetra CLI is the client.

### How to install Tetragon?

The README points to the official documentation rather than giving commands inline. It links getting started guides for Kubernetes and for Linux with Docker, a deployment guide, and a separate page for installing the tetra CLI. On Kubernetes the chart lives under install/ and the operator under operator/ manages the agent.

### Is Tetragon the same as Cilium?

No. Tetragon is described as Cilium's component, but Cilium's core is network policy and connectivity while Tetragon works at the process and syscall layer. The README lists network observability as one Tetragon use case, so they overlap there, but neither replaces the other.

## Sources

- [Official documentation](https://tetragon.io)
- [Official README](https://github.com/cilium/tetragon#readme)
- [Project repository](https://github.com/cilium/tetragon)
- [Release notes](https://github.com/cilium/tetragon/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cilium-tetragon