feat: handle parse collected environment variables in execve events

This patch adds:
1. Adds a new field `envs` to the `ExecveEvent` message in the Tetragon API.
2. Updates the Go API to include the new `envs` field in the `ExecveEvent` struct.
3. Adds `--enable-process-environment-variables` flag to conditionally read env vars with ProcessExec events

Partially resolves #2648

Signed-off-by: Mikita Iwanowski <[email protected]>

Author: slntopp

pkg/api/confapi/confapi.go

@@ -10,6 +10,7 @@ type TetragonConf struct {
 	TgCgrpHierarchy uint32 `align:"tg_cgrp_hierarchy"`  // Tetragon Cgroup tracking hierarchy ID
 	TgCgrpSubsysIdx uint32 `align:"tg_cgrp_subsys_idx"` // Tracking Cgroup css idx at compile time
 	TgCgrpLevel     uint32 `align:"tg_cgrp_level"`      // Tetragon cgroup level
+	EnvVarsEnabled  uint64 `align:"env_vars_enabled"`   // Whether to read environment variables
 	TgCgrpId        uint64 `align:"tg_cgrpid"`          // Tetragon cgroup ID
 	CgrpFsMagic     uint64 `align:"cgrp_fs_magic"`      // Cgroupv1 or cgroupv2
 }

pkg/api/flags.go

@@ -10,15 +10,15 @@ const (
 	// EventProcFS for the other option. A correctly formatted event should
 	// either set EventExecve or EventProcFS.
 	EventExecve = 0x01
-	// Available for use
-	EventAvail1 = 0x02
+	// EventEnvsData indicates environment variables are received with data event.
+	EventDataEnvs = 0x02
 	// EventProcFS indicates the event is generated from a proc interface.
 	// This happens at Tetragon init when existing processes are being loaded
 	// into Tetragon event buffer. All events should have either EventExecve or
 	// EventProcFS set.
 	EventProcFS = 0x04
-	// Available for use
-	EventAvail2 = 0x08
+	// EventEnvsError indicates an error happened when storing environment variables.
+	EventErrorEnvs = 0x08
 	// EventTruncArgs indicates we truncated the processes arguments because
 	// the buffer size was too small to fit all exec args. Consider increasing
 	// buffer size to avoid this.

pkg/api/processapi/processapi.go

@@ -80,7 +80,7 @@ type MsgExec struct {
 	SizePath   uint16
 	SizeArgs   uint16
 	SizeCwd    uint16
-	Pad2       uint16
+	SizeEnvs   uint16
 }
 
 type MsgExecveKey struct {
@@ -210,6 +210,7 @@ type MsgProcess struct {
 	Ktime      uint64
 	Filename   string
 	Args       string
+	Envs       string
 	User       MsgUserRecord
 }
 

pkg/grpc/exec/exec.go

@@ -81,6 +81,10 @@ func GetProcessExec(event *MsgExecveEventUnix, useCache bool) *tetragon.ProcessE
 		Ancestors: tetragonAncestors,
 	}
 
+	if option.Config.EnableProcessEnvironmentVariables {
+		tetragonEvent.EnvironmentVariables = proc.GetEnvironmentVariables()
+	}
+
 	if tetragonProcess.Pid == nil {
 		eventcache.CacheErrors(eventcache.NilProcessPid, notify.EventType(tetragonEvent)).Inc()
 		return nil

pkg/option/config.go

@@ -33,12 +33,13 @@ type config struct {
 
 	EnablePodAnnotations bool
 
-	EnableProcessAncestors           bool
-	EnableProcessKprobeAncestors     bool
-	EnableProcessTracepointAncestors bool
-	EnableProcessUprobeAncestors     bool
-	EnableProcessLsmAncestors        bool
-	EnableProcessUsdtAncestors       bool
+	EnableProcessAncestors            bool
+	EnableProcessKprobeAncestors      bool
+	EnableProcessTracepointAncestors  bool
+	EnableProcessUprobeAncestors      bool
+	EnableProcessLsmAncestors         bool
+	EnableProcessUsdtAncestors        bool
+	EnableProcessEnvironmentVariables bool
 
 	EnableProcessNs      bool
 	EnableProcessCred    bool

pkg/option/flags.go

@@ -51,6 +51,8 @@ const (
 	KeyServerAddress      = "server-address"
 	KeyGopsAddr           = "gops-address"
 
+	KeyEnableProcessEnvironmentVariables = "enable-process-environment-variables"
+
 	KeyEnableAncestors   = "enable-ancestors"
 	KeyEnableProcessCred = "enable-process-cred"
 	KeyEnableProcessNs   = "enable-process-ns"
@@ -195,6 +197,8 @@ func ReadAndSetFlags() error {
 		Config.EnableProcessUsdtAncestors = slices.Contains(enableAncestors, "usdt")
 	}
 
+	Config.EnableProcessEnvironmentVariables = viper.GetBool(KeyEnableProcessEnvironmentVariables)
+
 	Config.GopsAddr = viper.GetString(KeyGopsAddr)
 
 	logLevel := viper.GetString(KeyLogLevel)
@@ -386,6 +390,8 @@ func AddFlags(flags *pflag.FlagSet) {
 	flags.Bool(KeyEnablePodAnnotations, false, "Add pod annotations field to events.")
 	flags.StringSlice(KeyEnableAncestors, []string{}, "Comma-separated list of process event types to enable ancestors for. Supported event types are: base, kprobe, tracepoint, uprobe, lsm, usdt. Unknown event types will be ignored. Type 'base' enables ancestors for process_exec and process_exit events and is required by all other supported event types for correct reference counting. An empty string disables ancestors completely")
 
+	flags.Bool(KeyEnableProcessEnvironmentVariables, false, "Include environment variables in process_exec events. Disabled by default. Note that this option can significantly increase the size of the events and may impact performance")
+
 	// Tracing policy file
 	flags.String(KeyTracingPolicy, "", "Tracing policy file to load at startup")
 

pkg/process/process.go

@@ -48,6 +48,10 @@ type ProcessInternal struct {
 	// will be constructed on the fly when returning these extra fields
 	// about the binary during the corresponding ProcessExec only.
 	apiBinaryProp *tetragon.BinaryProperties
+	// EnvironmentVariables is a string map of unprocessed environment variables
+	// that were passed to the process. This is not stored into the process,
+	// but is used to construct the ProcessExec event.
+	environmentVariables string
 	// garbage collector metadata
 	color  int // Writes should happen only inside gc select channel
 	refcnt atomic.Uint32
@@ -239,6 +243,14 @@ func (pi *ProcessInternal) NeededAncestors() bool {
 	return false
 }
 
+func (pi *ProcessInternal) GetEnvironmentVariables() string {
+	if pi == nil {
+		return ""
+	}
+
+	return pi.environmentVariables
+}
+
 // UpdateEventProcessTID Updates the Process.Tid of the event on the fly.
 //
 // From BPF side as we track processes by their TGID we do not cache TIDs,
@@ -383,11 +395,12 @@ func initProcessInternalExec(
 			Refcnt:       0,
 			User:         user,
 		},
-		capabilities:  apiCaps,
-		apiCreds:      apiCreds,
-		apiBinaryProp: apiBinaryProp,
-		namespaces:    apiNs,
-		refcntOps:     map[string]int32{"process++": 1},
+		capabilities:         apiCaps,
+		apiCreds:             apiCreds,
+		apiBinaryProp:        apiBinaryProp,
+		environmentVariables: process.Envs,
+		namespaces:           apiNs,
+		refcntOps:            map[string]int32{"process++": 1},
 	}
 	pi.refcnt.Store(1)
 

pkg/sensors/config/confmap/confmap.go

@@ -34,6 +34,7 @@ type TetragonConfValue struct {
 	TgCgrpHierarchy   uint32   `align:"tg_cgrp_hierarchy"`    // Tetragon Cgroup tracking hierarchy ID
 	TgCgrpv1SubsysIdx uint32   `align:"tg_cgrpv1_subsys_idx"` // Tracking Cgroupv1 css idx at compile time
 	TgCgrpLevel       uint32   `align:"tg_cgrp_level"`        // Tetragon cgroup level
+	EnvVarsEnabled    uint64   `align:"env_vars_enabled"`     // Whether to read environment variables
 	TgCgrpId          uint64   `align:"tg_cgrpid"`            // Tetragon cgroup ID
 	CgrpFsMagic       uint64   `align:"cgrp_fs_magic"`        // Cgroupv1 or cgroupv2
 	UsePerfRingBuf    uint8    `align:"use_perf_ring_buf"`    // Use the perf ring buffer rather than the bpf ring buffer
@@ -125,6 +126,10 @@ func UpdateTgRuntimeConf(mapDir string, nspid int) error {
 		UsePerfRingBuf:    usePerfRingBuffer,
 	}
 
+	if option.Config.EnableProcessEnvironmentVariables {
+		v.EnvVarsEnabled = 1 // Set to 1 if environment variable reading is enabled
+	}
+
 	if err := UpdateConfMap(mapDir, v); err != nil {
 		log.Warn("failed to update map", "confmap-update", configMapName, logfields.Error, err)
 		return err

pkg/sensors/exec/exec_linux.go

@@ -84,6 +84,7 @@ func execParse(reader *bytes.Reader) (processapi.MsgProcess, error) {
 	proc := processapi.MsgProcess{
 		Filename: "<enomem>",
 		Args:     "<enomem>",
+		Envs:     "<enomem>",
 		Size:     processapi.MSG_SIZEOF_EXECVE,
 	}
 	exec := processapi.MsgExec{}
@@ -110,9 +111,9 @@ func execParse(reader *bytes.Reader) (processapi.MsgProcess, error) {
 		return proc, err
 	}
 
-	if size != uint32(exec.SizePath+exec.SizeArgs+exec.SizeCwd) {
-		err := fmt.Errorf("msg exec size larger than argsbuffer, size %d != %d, SizePath %d, SizeArgs %d, SizeCwd %d",
-			size, exec.SizePath+exec.SizeArgs+exec.SizeCwd, exec.SizePath, exec.SizeArgs, exec.SizeCwd)
+	if size != uint32(exec.SizePath+exec.SizeArgs+exec.SizeCwd+exec.SizeEnvs) {
+		err := fmt.Errorf("msg exec size larger than argsbuffer, size %d != %d, SizePath %d, SizeArgs %d, SizeCwd %d, SizeEnvs %d",
+			size, exec.SizePath+exec.SizeArgs+exec.SizeCwd, exec.SizePath, exec.SizeArgs, exec.SizeCwd, exec.SizeEnvs)
 		return proc, err
 	}
 
@@ -176,6 +177,26 @@ func execParse(reader *bytes.Reader) (processapi.MsgProcess, error) {
 		cmdArgs = append(cmdArgs, cwd)
 	}
 
+	if exec.SizeEnvs != 0 {
+		var data []byte
+		var err error
+
+		if exec.Flags&api.EventDataEnvs != 0 {
+			data, err = readData(exec.SizeEnvs)
+			if err != nil {
+				return proc, err
+			}
+			// cut the zero byte
+			data = data[:len(data)-1]
+		} else {
+			data = make([]byte, exec.SizeEnvs)
+			if err := binary.Read(reader, binary.LittleEndian, &data); err != nil {
+				return proc, err
+			}
+		}
+		proc.Envs = strutils.UTF8FromBPFBytes(bytes.ReplaceAll(data, []byte{0x00}, []byte{' '}))
+	}
+
 	proc.Size = exec.Size
 	proc.Args = strutils.UTF8FromBPFBytes(bytes.Join(cmdArgs[0:], []byte{0x00}))
 	return proc, nil