exectrace

SimpleeBPF-based exec snooping on Linux packaged as a Golibrary.

exectrace loads a pre-compiledeBPF program into the runningkernel to receive details about theexec family of syscalls.

Coder

exectrace provides workspace process logging for Coder v1 andCoder v2 (aka. Coder OSS).

Documentation for how to setup workspace process logging for Coder v1 users canbe foundhere.

Documentation for Coder v2 users can be found inenterprise/README.md.

Requirements

exectrace only supports Go 1.16+ and Linux kernel 5.8+ (due to the use ofBPF_MAP_TYPE_RINGBUF). Additionally, the kernel configCONFIG_DEBUG_INFO_BTF=y is required.

To validate this config is enabled, run either of the following commandsdirectly on the system:

$ cat /proc/config.gz | gunzip | grep CONFIG_DEBUG_INFO_BTF

$ cat "/boot/config-$(uname -r)" | grep CONFIG_DEBUG_INFO_BTF

Installation

$ go get -u github.com/coder/exectrace

Quickstart

You will need root access,CAP_SYS_ADMIN orCAP_BPF, to run eBPF programs onyour system.

Usego run -exec sudo ./cmd/program to compile a program and start it withsudo

$ go install -u github.com/coder/exectrace/cmd/exectrace$ exectrace --help...$ sudo exectrace2021/12/01 16:42:02 Waiting for events..[1188921, comm="node", uid=1002, gid=1003, filename=/bin/sh] /bin/sh -c 'which ps'[1188922, comm="sh", uid=1002, gid=1003, filename=/usr/bin/which] which ps

Usage

exectrace exposes a minimal API surface. Callexectrace.New(nil) and then youcan start reading events from the returnedTracer.

It is important that you close the tracer to avoid leaking kernel resources, sowe recommend implementing a simple signal handler like the one in this example:

package mainimport ("fmt""os""os/signal""syscall""github.com/coder/exectrace")func main() {tracer, err := exectrace.New(nil)if err != nil {panic(err)}defer tracer.Close()go func() {sigs := make(chan os.Signal, 1)signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)<-sigstracer.Close()}()for {event, err := tracer.Read()if err != nil {panic(err)}fmt.Printf("%+v\n", event)}}

For a full usage example, refer to thiscomprehensive program that uses the library.

Development

You will need the following:

• Docker (the Makefile runs clang within a Docker container for reproducibility)
• Golang 1.20+
• golangci-lint
• prettier
• shellcheck

Since the eBPF program is packaged usinggo:embed, you will need to compilethe program and include it in the repo.

If you change the files in thebpf directory, runmake and ensure that youinclude the.o files you changed in your commit (CI will verify that you'vedone this correctly).

Status: stable

This library is ready to use as-is. It has been used in production for years andhas received minimal maintenance over that time period.

In April 2024, a system to send logs from the kernel to userspace was addedwhich can make discovering potential issues in production/development mucheasier.

The API will likely not be further modified as we have no need for additionalfields/features. We will continue to maintain the library as needed.

See also

• canonical/etrace - Go binary thatuses ptrace and tracks the processes that a command launches for debugging andanalysis
• shirou/gopsutil - Go library that hasmethods for listing process details and getting information about the system

Dual licensed under the MIT and GPL 2.0 licenses. SeeLICENSE.

Code in the enterprise directory has a different license. SeeLICENSE.enterprise.

Constants¶

Variables¶

var NativeEndian =binary.LittleEndian

Functions¶

func GetPidNS() (uint32,error)

Types¶

type Event struct {Filenamestring `json:"filename"`// Argv contains the raw argv supplied to the process, including argv[0]// (which is equal to `filepath.Base(e.Filename)` in most circumstances).Argv []string `json:"argv"`// Truncated is true if we were unable to read all process arguments into// Argv because there were more than 32 arguments, or if one of the// arguments was greater than or equal to 1023 bytes in length.//// It may indicate that the user or process is trying to hide arguments from// the tracer.Truncatedbool `json:"truncated"`// These values are of the new process. Keep in mind that the exec call may// fail and the PID will be released in such a case.PIDuint32 `json:"pid"`UIDuint32 `json:"uid"`GIDuint32 `json:"gid"`// Comm is the "name" of the parent process, usually the filename of the// executable (but not always).Commstring `json:"comm"`}

type Tracer interface {io.Closer// Read blocks until an exec event is available, then returns it.Read() (*Event,error)// FD returns the FD of the loaded eBPF program. This is useful for// benchmarking.FD()int}

func New(opts *TracerOpts) (Tracer,error)

type TracerOpts struct {// PidNS filters all processes that are in the given PID namespace or in the// child namespace tree of this given namespace. This is very useful for// Docker containers, as you can read all processes in a container (or in// child containers).//// You can read the PID namespace ID for a given process by running// `readlink /proc/x/ns/pid`.//// This filter runs in the kernel for high performance.PidNSuint32// LogFn is called for each log line that is read from the kernel. All logs// are considered error logs unless running a debug version of the eBPF// program.//// If unspecified, a default log function is used that logs to stderr.LogFn func(uid, gid, piduint32, logLinestring)}