utils

Documentation

Overview

Package utils contains common code shared across the USM codebase

Index

• Variables
• func AddAttacher(moduleName, name string, a Attacher)
• func GetAttachPIDEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)
• func GetBlockedPathIDEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)
• func GetClearBlockedEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)
• func GetDetachPIDEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)
• func GetTracedProgramsEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)
• type Attacher
• type BlockListEntry
• type BlockedProcess
  • func GetBlockedPathIDsList(moduleName string) []BlockedProcess
• type Callback
• type FilePath
  • func NewFilePath(procRoot, namespacedPath string, pid uint32) (FilePath, error)
• type FileRegistry
  • func NewFileRegistry(moduleName, 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, ...) 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 PathIdentifierWithSamplePath
• type TracedProgram
  • func GetTracedProgramList(moduleName string) []TracedProgram

Variables

var ErrEnvironment = errors.New("Environment error, path will not be blocked")

ErrEnvironment indicates that the error is not with the path itself, so the path itself should not be blocked from further attempts at hooking.

var (

	// ErrPathIsAlreadyRegistered is the error resulting if the
	// path is already in the file registry.
	ErrPathIsAlreadyRegistered = errors.New("path is already registered")
)

var IgnoreCB = func(FilePath) error { return nil }

IgnoreCB is just a dummy callback that doesn't do anything Meant for testing purposes

Functions

func AddAttacher

func AddAttacher(moduleName, name string, a Attacher)

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

func GetAttachPIDEndpoint

func GetAttachPIDEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)

GetAttachPIDEndpoint returns a callback for the given module name, that attaches a PID to an eBPF program.

func GetBlockedPathIDEndpoint

func GetBlockedPathIDEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)

GetBlockedPathIDEndpoint returns a callback for the given module name, that generates a summary of all blocked uprobe-based programs that are blocked in the registry along with their device and inode numbers, and sample path. This is used for debugging purposes only.

func GetClearBlockedEndpoint

func GetClearBlockedEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)

GetClearBlockedEndpoint returns a callback for the given module name, that clears the lists of blocked paths.

func GetDetachPIDEndpoint

func GetDetachPIDEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)

GetDetachPIDEndpoint returns a callback for the given module name, that detaches a PID from an eBPF program.

func GetTracedProgramsEndpoint

func GetTracedProgramsEndpoint(moduleName string) func(http.ResponseWriter, *http.Request)

GetTracedProgramsEndpoint returns a callback for the given module name, that 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 BlockListEntry

type BlockListEntry struct {
	Path   string
	Reason string
}

BlockListEntry represents an enty in the block list

type BlockedProcess

type BlockedProcess struct {
	ProgramType     string
	PathIdentifiers []PathIdentifierWithSamplePath
}

BlockedProcess represents an active uprobe-based program and its blocked PIDs.

func GetBlockedPathIDsList

func GetBlockedPathIDsList(moduleName string) []BlockedProcess

GetBlockedPathIDsList returns a list of PathIdentifiers blocked in the registry for the all programs type.

type Callback

type Callback func(FilePath) error

Callback is a function that is executed when a file becomes active or inactive

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(moduleName, 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, alreadyRegistered 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 PathIdentifierWithSamplePath

type PathIdentifierWithSamplePath struct {
	PathIdentifier
	SamplePath string
	Reason     string
}

PathIdentifierWithSamplePath extends `PathIdentifier` to have a sample path.

type TracedProgram

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

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

func GetTracedProgramList

func GetTracedProgramList(moduleName string) []TracedProgram

GetTracedProgramList returns a list of traced programs.