Tetragon Documentation

Tetragon provides Kubernetes Identity Aware Policies designed for dynamic, ephemeral container environments. Instead of applying uniform policies to static infrastructure, Tetragon uses eBPF for in-kernel filtering based on Kubernetes-specific constructs. This allows for precise security observability and runtime enforcement that targets specific workloads, reducing noise and performance overhead.

Key capabilities include:

• In-kernel filtering: Enforce policies using Kubernetes constructs like namespaces, pod labels, and container fields.
• Precise Workload Control: Focus monitoring and enforcement on specific high-risk namespaces or critical workloads.
• Dynamic Enforcement: Adapt to changing workloads in ephemeral environments.
• Broad Runtime Support: Compatible with both containerd and CRI-O runtimes.

A TracingPolicy is a Kubernetes Custom Resource (CR) used to define how Tetragon observes kernel and userspace events via eBPF. It allows you to specify hook points, in-kernel filtering via selectors, and actions to take when events match.

Supported hook points include:

• kprobes
• uprobes
• tracepoints
• LSM hooks
• USDTs

Policies can be managed in Kubernetes using kubectl or GitOps tools like Argo CD. For non-Kubernetes environments, policies can be applied via the tetra-cli or through Tetragon daemon configuration flags.

Tetragon Runtime Hooks address the delay between container start and Kubernetes (K8s) identity application. While Tetragon can fetch pod information (namespaces, labels) from the K8s API server, this can lead to a window where enforcement policies are not yet active.

Runtime hooks solve this by 'hooking' into the container runtime to ensure the Tetragon agent sets up necessary filtering state before the container starts. This is achieved using the tetragon-oci-hook binary, which communicates with the Tetragon agent via a gRPC UNIX socket (tetragon.sock).

Tetragon's threat model helps users and operators understand security implications, identify attack vectors, and implement defensive controls. Tetragon uses eBPF for runtime security enforcement and observability.

Key considerations for security posture include:

• Deployment Scenarios: Kubernetes (DaemonSet), standalone containerized agents, or systemd-managed services.
• Attacker Profiles: The model evaluates threats from Kubernetes workloads, limited privilege host attackers, Kubernetes API server attackers, and root-equivalent host attackers.
• Policy Validation: When writing tracing policies, ensure chosen hook points are carefully validated to meet security/visibility objectives, as incorrect hook points can lead to visibility risks.

The Tetragon API is defined using Protocol Buffers (protobuf). The documentation is organized into several key proto files that define the communication between Tetragon and its clients:

• tetragon/bpf.proto: Defines BPF-related commands and program types.
• tetragon/capabilities.proto: Defines capability types and process privilege changes.
• tetragon/eventlogservice.proto: Defines the EventLogService for managing and retrieving event logs.
• tetragon/tetragon.proto: The core schema containing primary data structures like Process, Container, Pod, Namespace, and various Kprobe event types.
• tetragon/events.proto: Defines event streaming, filtering (e.g., FieldFilter, RedactionFilter), and aggregation options.
• tetragon/sensors.proto: Defines the sensor management API, including enabling/disabling sensors and managing tracing policies.

Tetragon tracing policies operate in three distinct modes that determine how enforcement actions are handled:

• monitoring: Enforcement operations are elided (ignored).
• enforcement: Enforcement operations are respected and performed.
• monitor_only: The policy contains no enforcement actions and therefore cannot be switched to enforcement mode.

You can inspect the current mode of your policies using the tetra CLI.

Tetragon provides deep insights into network events by linking network activity directly to the processes and workloads driving them. This allows for process-aware monitoring and socket lifecycle tracking in cloud-native environments.

Key capabilities include:

• Process-Aware Network Monitoring: Links every network event to specific processes and workloads for full context.
• Socket Lifecycle Insights: Tracks the entire lifecycle of sockets, including connections, sent/received bytes, and specific socket events.
• Kubernetes-Enriched Metadata: Automatically enhances network observability with Kubernetes identities, such as pod labels and namespaces.
• Comprehensive Visibility: Provides a holistic view of network activity to facilitate faster troubleshooting and improved security posture.

Contributions to Tetragon are not limited to code. You can support the project by:

• Writing content: Write blog posts about Tetragon or its use cases. These can be added to the project [resources]({{< ref "/docs/resources" >}}).
• Speaking: Present Tetragon at conferences or meetups. Video recordings can be added to [resources]({{< ref "/docs/resources" >}}).
• Community engagement: Share usage on social platforms and add yourself to the Cilium project user list.
• Issue tracking: Raise issues regarding bugs or feature enhancements via the GitHub issue tracker.
• Code review: Review existing pull requests to provide fresh perspectives on patches.
• Technical contributions: Submit patches for code or documentation improvements.

Tetragon provides real-time observability into operating system integrity by monitoring critical kernel-level operations. You can use Tetragon to:

• Audit Kernel Modules: Track the loading and unloading of kernel modules. Tetragon identifies the specific processes or containers responsible for these actions and captures whether the kernel module is signed, which helps ensure only verified code is integrated into the kernel.
• Observe eBPF Subsystem Interactions: Monitor eBPF program loads and interactions to detect suspicious activity or unauthorized modifications to the eBPF subsystem.

Tetragon's TracingPolicy is a Kubernetes custom resource (CR) used to trace arbitrary kernel events. A policy defines a hook point (supporting kprobes, tracepoints, and uprobes) and uses selectors for in-kernel filtering and specifying actions to take upon a match.

Warning: TracingPolicy provides low-level configuration. Users should have Linux kernel and container knowledge to avoid issues like TOCTOU (Time-of-Check to Time-of-Use) bugs.