Tetragon - eBPF Runtime Security Cheatsheet
Tetragon is an open-source eBPF-based runtime security and observability tool from the Cilium project (CNCF). It hooks the kernel to capture security-relevant events — process execution, file access, network connections, capability use, and privilege escalation — with very low overhead, and can enforce policy in-kernel (kill or override syscalls) rather than only alerting. It runs on Kubernetes or standalone on a Linux host.
Requirements
- Linux kernel with BTF (
/sys/kernel/btf/vmlinux present) — most modern distros
- Root / privileged container (eBPF needs
CAP_BPF / CAP_SYS_ADMIN)
Installation
Kubernetes (Helm)
helm repo add cilium https://helm.cilium.io
helm repo update
helm install tetragon cilium/tetragon -n kube-system
kubectl rollout status -n kube-system ds/tetragon -w
Standalone host (Docker)
docker run --name tetragon --rm --pull always \
--pid=host --cgroupns=host --privileged \
-v /sys/kernel:/sys/kernel \
quay.io/cilium/tetragon:latest
Install the tetra CLI
# Linux amd64
curl -L https://github.com/cilium/tetragon/releases/latest/download/tetra-linux-amd64.tar.gz | tar -xz
sudo mv tetra /usr/local/bin/
tetra version
Observing Events
| Command | Description |
|---|
kubectl exec -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact | Stream live events (Kubernetes) |
docker exec tetragon tetra getevents -o compact | Stream live events (standalone) |
tetra getevents | Full JSON event stream |
tetra getevents --processes | Only process exec/exit events |
tetra getevents --pods my-pod | Filter by pod |
| `tetra getevents -o json | jq` |
Compact output shows a one-line summary per event, e.g. process exec, file open, or connect, annotated with pod/binary/args.
TracingPolicy (What to Watch)
Tetragon’s behavior is driven by TracingPolicy custom resources (or local YAML in standalone mode). A policy attaches to kprobes/tracepoints/LSM hooks and optionally adds actions.
apiVersion: cilium.io/v1alpha1
kind: TracingPolicy
metadata:
name: monitor-sensitive-files
spec:
kprobes:
- call: "security_file_permission"
syscall: false
args:
- index: 0
type: "file"
selectors:
- matchArgs:
- index: 0
operator: "Prefix"
values:
- "/etc/shadow"
- "/etc/sudoers"
| Command | Description |
|---|
kubectl apply -f policy.yaml | Load a TracingPolicy (Kubernetes) |
kubectl get tracingpolicies | List active policies |
kubectl delete tracingpolicy NAME | Remove a policy |
tetra tracingpolicy add policy.yaml | Load a policy (standalone gRPC) |
tetra tracingpolicy list | List loaded policies (standalone) |
Enforcement Actions
Add a matchActions block to a selector to act in-kernel:
| Action | Effect |
|---|
Sigkill | Kill the offending process synchronously |
Override | Return a chosen error code from the syscall |
Post | Emit an event only (observe) |
NotifyEnforcer / Signal | Send a signal to the process |
matchActions:
- action: Sigkill # block, don't just log
Common Detections
| Goal | Approach |
|---|
| Process execution visibility | Built-in process exec/exit events (no policy needed) |
| Sensitive file access | kprobe on security_file_permission with path selectors |
| Privilege escalation | Watch capability changes / setuid family |
| Unexpected network egress | tcp connect hooks with CIDR selectors |
| Container escape attempts | Namespace/capability change monitoring |
Filtering & Output Tips
# Only show exec events for a specific binary
tetra getevents -o compact | grep curl
# Pretty, colorized compact stream
kubectl exec -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods web
# Export raw JSON for a SIEM pipeline
tetra getevents -o json >> /var/log/tetragon-events.json
Tetragon vs Falco
| Aspect | Tetragon | Falco |
|---|
| Engine | eBPF (Cilium) | eBPF / kernel module |
| Enforcement | Yes (in-kernel kill/override) | Alerting-focused |
| Policy model | TracingPolicy CRDs | Falco rules (YAML) |
| K8s identity context | Strong (pod/labels) | Yes |
| Best for | Prevention + deep kernel visibility | Mature rule library, detection |
Resources
