v1/

README

Protocol Documentation

Table of Contents

• tetragon/capabilities.proto

  • CapabilitiesType

• tetragon/tetragon.proto

  • Capabilities

  • Container

  • CreateContainer

  • CreateContainer.AnnotationsEntry

  • GetHealthStatusRequest

  • GetHealthStatusResponse

  • HealthStatus

  • Image

  • KprobeArgument

  • KprobeBpfAttr

  • KprobeBpfMap

  • KprobeCapability

  • KprobeCred

  • KprobeFile

  • KprobePath

  • KprobePerfEvent

  • KprobeSkb

  • KprobeSock

  • KprobeTruncatedBytes

  • KprobeUserNamespace

  • Namespace

  • Namespaces

  • Pod

  • Pod.PodLabelsEntry

  • Process

  • ProcessExec

  • ProcessExit

  • ProcessKprobe

  • ProcessLoader

  • ProcessTracepoint

  • RuntimeHookRequest

  • RuntimeHookResponse

  • Test

  • HealthStatusResult

  • HealthStatusType

  • KprobeAction

• tetragon/events.proto

  • AggregationInfo

  • AggregationOptions

  • FieldFilter

  • Filter

  • GetEventsRequest

  • GetEventsResponse

  • EventType

  • FieldFilterAction

• tetragon/stack.proto

  • StackAddress
  • StackTrace
  • StackTraceLabel
  • StackTraceNode

• tetragon/sensors.proto

  • AddTracingPolicyRequest

  • AddTracingPolicyResponse

  • DeleteTracingPolicyRequest

  • DeleteTracingPolicyResponse

  • DisableSensorRequest

  • DisableSensorResponse

  • EnableSensorRequest

  • EnableSensorResponse

  • GetSensorConfigRequest

  • GetSensorConfigResponse

  • GetStackTraceTreeRequest

  • GetStackTraceTreeResponse

  • GetVersionRequest

  • GetVersionResponse

  • ListSensorsRequest

  • ListSensorsResponse

  • RemoveSensorRequest

  • RemoveSensorResponse

  • SensorStatus

  • SetSensorConfigRequest

  • SetSensorConfigResponse

  • FineGuidanceSensors

• Scalar Value Types

Top

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

Top

tetragon/tetragon.proto

Capabilities

Field	Type	Label	Description
permitted	CapabilitiesType	repeated
effective	CapabilitiesType	repeated
inheritable	CapabilitiesType	repeated

Container

Field	Type	Label	Description
id	string
name	string
image	Image
start_time	google.protobuf.Timestamp		Start time of the container.
pid	google.protobuf.UInt32Value		PID 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.

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

CreateContainer.AnnotationsEntry

Field	Type	Label	Description
key	string
value	string

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
name	string

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
capability_arg	KprobeCapability

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

KprobePath

Field	Type	Label	Description
mount	string
path	string
flags	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

KprobeSock

Field	Type	Label	Description
family	string
type	string
protocol	string
mark	uint32
priority	uint32
saddr	string
daddr	string
sport	uint32
dport	uint32

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
is_host	bool

Namespaces

Field	Type	Label	Description
uts	Namespace
ipc	Namespace
mnt	Namespace
pid	Namespace
pid_for_children	Namespace
net	Namespace
time	Namespace
time_for_children	Namespace
cgroup	Namespace
user	Namespace

Pod

Field	Type	Label	Description
namespace	string
name	string
labels	string	repeated
container	Container
pod_labels	Pod.PodLabelsEntry	repeated	pod_labels field contains all the labels of the pod. Note that the labels field contains Cilium identity labels, which is a subset of pod labels.

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
uid	google.protobuf.UInt32Value
cwd	string
binary	string
arguments	string
flags	string
start_time	google.protobuf.Timestamp
auid	google.protobuf.UInt32Value
pod	Pod
docker	string
parent_exec_id	string
refcnt	uint32
cap	Capabilities
ns	Namespaces

ProcessExec

Field	Type	Label	Description
process	Process
parent	Process
ancestors	Process	repeated	Ancestors of the process beyond the immediate parent.

ProcessExit

Field	Type	Label	Description
process	Process
parent	Process
signal	string
status	uint32
time	google.protobuf.Timestamp

ProcessKprobe

Field	Type	Label	Description
process	Process
parent	Process
function_name	string
args	KprobeArgument	repeated
return	KprobeArgument
action	KprobeAction

ProcessLoader

loader sensor event triggered for loaded binary/library

Field	Type	Label	Description
process	Process
path	string
buildid	bytes

ProcessTracepoint

Field	Type	Label	Description
process	Process
parent	Process
subsys	string
event	string
args	KprobeArgument	repeated	TODO: once we implement all we want, rename KprobeArgument to GenericArgument

RuntimeHookRequest

RuntimeHookRequest synchronously propagates information to the agent about run-time state.

Field	Type	Label	Description
createContainer	CreateContainer

RuntimeHookResponse

Test

Field	Type	Label	Description
arg0	uint64
arg1	uint64
arg2	uint64
arg3	uint64

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
KPROBE_ACTION_POST	1
KPROBE_ACTION_FOLLOWFD	2
KPROBE_ACTION_SIGKILL	3
KPROBE_ACTION_UNFOLLOWFD	4
KPROBE_ACTION_OVERRIDE	5
KPROBE_ACTION_COPYFD	6
KPROBE_ACTION_GETURL	7
KPROBE_ACTION_DNSLOOKUP	8

Top

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.

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
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).

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
process_exit	ProcessExit
process_kprobe	ProcessKprobe
process_tracepoint	ProcessTracepoint
process_loader	ProcessLoader
test	Test
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. |

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
TEST	40000

FieldFilterAction

Determins the behaviour of a field filter

Name	Number	Description
INCLUDE	0
EXCLUDE	1

Top

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

Top

tetragon/sensors.proto

AddTracingPolicyRequest

Field	Type	Label	Description
yaml	string

AddTracingPolicyResponse

DeleteTracingPolicyRequest

Field	Type	Label	Description
yaml	string

DeleteTracingPolicyResponse

DisableSensorRequest

Field	Type	Label	Description
name	string

DisableSensorResponse

EnableSensorRequest

Field	Type	Label	Description
name	string

EnableSensorResponse

GetSensorConfigRequest

Field	Type	Label	Description
name	string
cfgkey	string

GetSensorConfigResponse

Field	Type	Label	Description
cfgval	string

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

RemoveSensorRequest

Field	Type	Label	Description
name	string

RemoveSensorResponse

SensorStatus

Field	Type	Label	Description
name	string
enabled	bool

SetSensorConfigRequest

Field	Type	Label	Description
name	string
cfgkey	string
cfgval	string

SetSensorConfigResponse

FineGuidanceSensors

Method Name	Request Type	Response Type	Description
GetEvents	GetEventsRequest	GetEventsResponse stream
GetHealth	GetHealthStatusRequest	GetHealthStatusResponse
AddTracingPolicy	AddTracingPolicyRequest	AddTracingPolicyResponse
RemoveSensor	RemoveSensorRequest	RemoveSensorResponse
ListSensors	ListSensorsRequest	ListSensorsResponse
EnableSensor	EnableSensorRequest	EnableSensorResponse
DisableSensor	DisableSensorRequest	DisableSensorResponse
SetSensorConfig	SetSensorConfigRequest	SetSensorConfigResponse
GetSensorConfig	GetSensorConfigRequest	GetSensorConfigResponse
GetStackTraceTree	GetStackTraceTreeRequest	GetStackTraceTreeResponse
GetVersion	GetVersionRequest	GetVersionResponse
RuntimeHook	RuntimeHookRequest	RuntimeHookResponse

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)