tracer

Documentation

Overview

Package tracer implements Linux ptrace-based exec interception for the target process tree. It receives shim, broker, whitelist, environment, and child-command configuration from mproxy-tracer, and feeds non-whitelisted exec calls through mproxy-shim with environment-change metadata for downstream filtering.

Index

• func ReadPointer(pid int, addr uintptr) (uintptr, error)
• func ReadString(pid int, addr uintptr) (string, error)
• func ReadStringArray(pid int, addr uintptr) ([]string, error)
• func SeccompArch() uint32
• func SysExecve() uint32
• func SysExecveat() uint32
• func WriteBytes(pid int, addr uintptr, data []byte) error
• func WriteStringArray(pid int, addr uintptr, strs []string) (int, error)
• type Config
• type EnvBaseline
  • func NewEnvBaselineFromSlice(env []string) *EnvBaseline
  • func (b *EnvBaseline) ChangedKeys(current []string) string
  • func (b *EnvBaseline) InjectEnvVars(envp []string) []string
• type SyscallRegs
  • func GetRegs(pid int) (*SyscallRegs, error)
  • func (r *SyscallRegs) ArgvAddr(isExecveat bool) uintptr
  • func (r *SyscallRegs) BlockSyscall()
  • func (r *SyscallRegs) EnvpAddr(isExecveat bool) uintptr
  • func (r *SyscallRegs) PathAddr(isExecveat bool) uintptr
  • func (r *SyscallRegs) Set(pid int) error
  • func (r *SyscallRegs) SetArgvAddr(isExecveat bool, addr uintptr)
  • func (r *SyscallRegs) SetEnvpAddr(isExecveat bool, addr uintptr)
  • func (r *SyscallRegs) SetPathAddr(isExecveat bool, addr uintptr)
  • func (r *SyscallRegs) StackPointer() uintptr
  • func (r *SyscallRegs) SyscallNum() uint64
• type Tracer
  • func New(cfg Config) *Tracer
  • func (t *Tracer) Start(ctx context.Context, argv []string, env []string, onStart func(childPid int)) (int, error)

Functions

func ReadPointer

func ReadPointer(pid int, addr uintptr) (uintptr, error)

ReadPointer reads a single pointer-sized value from the tracee.

func ReadString

func ReadString(pid int, addr uintptr) (string, error)

ReadString reads a NUL-terminated string from the tracee's address space.

func ReadStringArray

func ReadStringArray(pid int, addr uintptr) ([]string, error)

ReadStringArray reads a NULL-terminated array of string pointers from the tracee (e.g. argv or envp).

func SeccompArch

func SeccompArch() uint32

func SysExecve

func SysExecve() uint32

func SysExecveat

func SysExecveat() uint32

func WriteBytes

func WriteBytes(pid int, addr uintptr, data []byte) error

WriteBytes writes data into the tracee's address space at the given address.

func WriteStringArray

func WriteStringArray(pid int, addr uintptr, strs []string) (int, error)

WriteStringArray writes a NULL-terminated string pointer array and all string data into the tracee at addr. Returns the total bytes consumed. Layout: [ptr0, ptr1, ..., NULL, "str0\0", "str1\0", ...]

Types

type Config

type Config struct {
	ShimPath   string       // Absolute path to mproxy-shim.
	Whitelist  []string     // Absolute paths that should execute locally.
	BrokerSock string       // Path to broker Unix socket.
	Log        *slog.Logger // Optional logger; defaults to slog.Default.
}

Config holds the tracer configuration.

type EnvBaseline

type EnvBaseline struct {
	// contains filtered or unexported fields
}

EnvBaseline holds a snapshot of the environment for computing diffs.

func NewEnvBaselineFromSlice

func NewEnvBaselineFromSlice(env []string) *EnvBaseline

NewEnvBaselineFromSlice creates a baseline from a string slice (e.g. os.Environ()).

func (*EnvBaseline) ChangedKeys

func (b *EnvBaseline) ChangedKeys(current []string) string

ChangedKeys computes which env var names in current are new or differ from the baseline. Returns the colon-separated string for MPROXY_CHANGED_ENVS, or empty string if nothing changed.

func (*EnvBaseline) InjectEnvVars

func (b *EnvBaseline) InjectEnvVars(envp []string) []string

InjectEnvVars appends or replaces MPROXY_HOOK_BYPASS=1 and MPROXY_CHANGED_ENVS=... in the given envp slice.

type SyscallRegs

type SyscallRegs struct {
	// contains filtered or unexported fields
}

SyscallRegs holds the register state for a syscall on amd64. On execve(pathname, argv, envp):

• Orig_rax = syscall number
• Rdi = pathname pointer
• Rsi = argv pointer
• Rdx = envp pointer For execveat(dirfd, pathname, argv, envp, flags):
• Rdi = dirfd
• Rsi = pathname pointer
• Rdx = argv pointer
• R10 = envp pointer
• R8 = flags

func GetRegs

func GetRegs(pid int) (*SyscallRegs, error)

GetRegs reads the tracee's register state.

func (*SyscallRegs) ArgvAddr

func (r *SyscallRegs) ArgvAddr(isExecveat bool) uintptr

ArgvAddr returns the pointer to the argv array.

func (*SyscallRegs) BlockSyscall

func (r *SyscallRegs) BlockSyscall()

BlockSyscall replaces the pending syscall with an invalid syscall number so a failed rewrite cannot fall through and execute locally.

func (*SyscallRegs) EnvpAddr

func (r *SyscallRegs) EnvpAddr(isExecveat bool) uintptr

EnvpAddr returns the pointer to the envp array.

func (*SyscallRegs) PathAddr

func (r *SyscallRegs) PathAddr(isExecveat bool) uintptr

PathAddr returns the pointer to the pathname argument. For execve this is arg0 (rdi), for execveat it's arg1 (rsi).

func (*SyscallRegs) Set

func (r *SyscallRegs) Set(pid int) error

SetRegs writes the register state back to the tracee.

func (*SyscallRegs) SetArgvAddr

func (r *SyscallRegs) SetArgvAddr(isExecveat bool, addr uintptr)

SetArgvAddr sets the argv pointer.

func (*SyscallRegs) SetEnvpAddr

func (r *SyscallRegs) SetEnvpAddr(isExecveat bool, addr uintptr)

SetEnvpAddr sets the envp pointer.

func (*SyscallRegs) SetPathAddr

func (r *SyscallRegs) SetPathAddr(isExecveat bool, addr uintptr)

SetPathAddr sets the pathname pointer.

func (*SyscallRegs) StackPointer

func (r *SyscallRegs) StackPointer() uintptr

StackPointer returns the current stack pointer.

func (*SyscallRegs) SyscallNum

func (r *SyscallRegs) SyscallNum() uint64

SyscallNum returns the invoked syscall number.

type Tracer

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer manages ptrace-based exec interception for all descendants of a traced process, redirecting non-whitelisted exec calls through mproxy-shim.

func New

func New(cfg Config) *Tracer

New creates a tracer with the given configuration.

func (*Tracer) Start

func (t *Tracer) Start(ctx context.Context, argv []string, env []string, onStart func(childPid int)) (int, error)

Start forks the target command under ptrace, then runs the trace loop intercepting execve/execveat calls. Returns the exit code. The optional onStart callback is invoked with the child pid after ptrace is configured but before the trace loop begins (useful for signal forwarding).