pathstub

Documentation

Overview

Package pathstub builds and serves a read-only FUSE directory that exposes one stub per executable reachable through the remote machine's $PATH. Reads on a stub proxy to the corresponding remote binary via SFTP; exec()-ing a stub gets rewritten by the broker's PathMapper to invoke the real remote path through mproxy-agent.

Index

• func EnumerateLocally(paths []string) ([]agentproto.PathInfoEntry, error)
• func FilterLocalCommands(entries []agentproto.PathInfoEntry, localCommands []string, mountPath string) []agentproto.PathInfoEntry
• func Mount(ctx context.Context, backend *FileSystem, mountpoint string) (*fuse.Server, error)
• type Entry
• type FileSystem
  • func New(opener RemoteOpener, info []agentproto.PathInfoEntry, log *slog.Logger) *FileSystem
  • func (f *FileSystem) Entries() map[string]Entry
  • func (f *FileSystem) Lookup(name string) (Entry, bool)
  • func (f *FileSystem) Names() []string
  • func (f *FileSystem) ReadFile(ctx context.Context, name string, off int64, size int) ([]byte, syscall.Errno)
• type RemoteOpener

Functions

func EnumerateLocally

func EnumerateLocally(paths []string) ([]agentproto.PathInfoEntry, error)

EnumerateLocally walks the listed PATH-style directories and returns one entry per executable file. If paths is empty, the agent's own $PATH is used (split on ":"). Within each directory entries are listed in name order; across directories the first occurrence of a name wins (mirroring real PATH lookup precedence).

Symlinks are followed (os.Stat) so the returned size/mtime/mode reflect the binary the kernel would execute. Non-regular files, directories, and files lacking any execute bit are skipped.

func FilterLocalCommands

func FilterLocalCommands(entries []agentproto.PathInfoEntry, localCommands []string, mountPath string) []agentproto.PathInfoEntry

FilterLocalCommands removes entries whose synthesised stub path (mountPath/<name>) would be matched by any rule in localCommands. This prevents the tracer from shadowing a binary the user explicitly opted to run locally with a remote-routing stub. mountPath is the configured container-side directory where the stub FUSE is bind-mounted.

Rule-by-rule behaviour (mirrors config.LocalCommandRule.Match):

• basename rule (e.g. "env") → filters out the matching stub.
• regex rule (e.g. "/^python.*/") → matched against the full synthetic path; rules anchored to "^/" or that include directory components will not match.
• absolute rule (e.g. "/usr/bin/env") → never filters, because the stub's pathname is <mountPath>/<name>, not /usr/bin/<name>. Use a basename rule if you want stub-level shadowing.

Invalid rules are silently skipped (the loader has already validated them; this is a defence-in-depth pass).

func Mount

func Mount(ctx context.Context, backend *FileSystem, mountpoint string) (*fuse.Server, error)

Mount mounts backend as a read-only FUSE filesystem at mountpoint. The returned server is unmounted automatically when ctx is canceled, or callers may call server.Unmount() directly.

Types

type Entry

type Entry struct {
	Name       string
	RemotePath string
	Mode       uint32
	Size       int64
	MTimeNanos int64
}

Entry is one immutable stub entry.

type FileSystem

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

FileSystem holds the immutable stub table plus the SFTP opener used for read-proxying. It is safe for concurrent use.

func New

func New(opener RemoteOpener, info []agentproto.PathInfoEntry, log *slog.Logger) *FileSystem

New constructs a FileSystem from enumeration entries. The entries map is copied so the caller can mutate the source slice afterwards.

func (*FileSystem) Entries

func (f *FileSystem) Entries() map[string]Entry

Entries returns a copy of the underlying map. Useful for building the broker's path mapper (stub-path → remote-path) without exposing the raw map.

func (*FileSystem) Lookup

func (f *FileSystem) Lookup(name string) (Entry, bool)

Lookup returns the entry for name and whether it exists.

func (*FileSystem) Names

func (f *FileSystem) Names() []string

Names returns the sorted list of stub names.

func (*FileSystem) ReadFile

func (f *FileSystem) ReadFile(ctx context.Context, name string, off int64, size int) ([]byte, syscall.Errno)

ReadFile proxies a read of name to its remote path. It mirrors workspacefs.FileSystem.ReadFile so the FUSE node implementations look nearly identical.

type RemoteOpener

type RemoteOpener interface {
	Open(path string) (remote.RemoteFile, error)
}

RemoteOpener opens a remote file by absolute path for reading. Today it is satisfied by remote.FileClient and any narrower interface that exposes Open(path) → (remote.RemoteFile, error).