utils

Documentation

Overview

Package utils contains common code shared across the USM codebase

Index

• func AddAttacher(name string, a Attacher)
• func AttachPIDEndpoint(w http.ResponseWriter, r *http.Request)
• func DetachPIDEndpoint(w http.ResponseWriter, r *http.Request)
• func TracedProgramsEndpoint(w http.ResponseWriter, _ *http.Request)
• type Attacher
• type FilePath
  • func NewFilePath(procRoot, namespacedPath string, pid uint32) (FilePath, error)
• type FileRegistry
  • func NewFileRegistry(programName string) *FileRegistry
  • func (r *FileRegistry) Clear()
  • func (r *FileRegistry) GetRegisteredProcesses() map[uint32]struct{}
  • func (r *FileRegistry) Log()
  • func (r *FileRegistry) Register(namespacedPath string, pid uint32, activationCB, deactivationCB callback) error
  • func (r *FileRegistry) Unregister(pid uint32) error
• type PathIdentifier
  • func NewPathIdentifier(path string) (pi PathIdentifier, err error)
  • func (p *PathIdentifier) Key() string
  • func (p *PathIdentifier) String() string
• type TracedProgram

Functions

func AddAttacher

func AddAttacher(name string, a Attacher)

AddAttacher adds an attacher to the debugger. Used to wrap the internal debugger instance.

func AttachPIDEndpoint

func AttachPIDEndpoint(w http.ResponseWriter, r *http.Request)

AttachPIDEndpoint attaches a PID to an eBPF program.

func DetachPIDEndpoint

func DetachPIDEndpoint(w http.ResponseWriter, r *http.Request)

DetachPIDEndpoint detaches a PID from an eBPF program.

func TracedProgramsEndpoint

func TracedProgramsEndpoint(w http.ResponseWriter, _ *http.Request)

TracedProgramsEndpoint generates a summary of all active uprobe-based programs along with their file paths and PIDs. This is used for debugging purposes only.

Types

type Attacher

type Attacher interface {
	// AttachPID attaches the provided PID to the eBPF program.
	AttachPID(pid uint32) error
	// DetachPID detaches the provided PID from the eBPF program.
	DetachPID(pid uint32) error
}

Attacher is the interface that represents a PID attacher/detacher. It is used to attach/detach a PID to/from an eBPF program.

type FilePath

type FilePath struct {
	HostPath string
	ID       PathIdentifier
	PID      uint32
}

FilePath represents the location of a file from the *root* namespace view

func NewFilePath

func NewFilePath(procRoot, namespacedPath string, pid uint32) (FilePath, error)

NewFilePath creates a new `FilePath` instance from a given `namespacedPath`

type FileRegistry

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

FileRegistry is responsible for tracking open files and executing callbacks *once* when they become "active" and *once* when they became "inactive", which means the point in time when no processes hold a file descriptor pointing to it.

Internally, we essentially store a reference counter for each `PathIdentifier`, which can be thought of as a global identifier for a file (a device/inode tuple);

We consider a file to be active when there is one or more open file descriptors pointing to it (reference count >= 1), and inactivate when all processes previously referencing terminate (reference count == 0);

The following example demonstrates the basic functionality of the `FileRegistry`:

PID 50 opens /foobar => *activation* callback is executed; /foobar references=1 PID 60 opens /foobar => no callback is executed; /foobar references=2 PID 50 terminates => no callback is executed; /foobar references=1 PID 60 terminates => *deactivation* callback is executed; /foobar references=0

func NewFileRegistry

func NewFileRegistry(programName string) *FileRegistry

NewFileRegistry creates a new `FileRegistry` instance

func (*FileRegistry) Clear

func (r *FileRegistry) Clear()

Clear removes all registrations calling their deactivation callbacks This function should be called once during in termination.

func (*FileRegistry) GetRegisteredProcesses

func (r *FileRegistry) GetRegisteredProcesses() map[uint32]struct{}

GetRegisteredProcesses returns a set with all PIDs currently being tracked by the `FileRegistry`

func (*FileRegistry) Log

func (r *FileRegistry) Log()

Log state of `FileRegistry`

func (*FileRegistry) Register

func (r *FileRegistry) Register(namespacedPath string, pid uint32, activationCB, deactivationCB callback) error

Register inserts or updates a new file registration within to the `FileRegistry`;

If no current registration exists for the given `PathIdentifier`, we execute its *activation* callback. Otherwise, we increment the reference counter for the existing registration if and only if `pid` is new;

func (*FileRegistry) Unregister

func (r *FileRegistry) Unregister(pid uint32) error

Unregister a PID if it exists

All files that were previously referenced by the given PID will have their reference counters decremented by one. For any file for the number of references drops to zero, we'll execute the *deactivationCB* previously supplied during the `Register` call.

type PathIdentifier

type PathIdentifier struct {
	Dev   uint64
	Inode uint64
}

PathIdentifier is the unique key (system wide) of a file based on dev/inode

func NewPathIdentifier

func NewPathIdentifier(path string) (pi PathIdentifier, err error)

NewPathIdentifier returns a new PathIdentifier instance Note that `path` must be an absolute path

func (*PathIdentifier) Key

func (p *PathIdentifier) Key() string

Key is a unique (system wide) TLDR Base64(murmur3.Sum64(device, inode)) It composes based the device (minor, major) and inode of a file murmur is a non-crypto hashing

As multiple containers overlayfs (same inode but could be overwritten with different binary)
device would be different

a Base64 string representation is returned and could be used in a file path

func (*PathIdentifier) String

func (p *PathIdentifier) String() string

type TracedProgram

type TracedProgram struct {
	ProgramType string
	FilePath    string
	PIDs        []uint32
}

TracedProgram represents an active uprobe-based program and its used for the purposes of generating JSON content in our debugging endpoint