clawkerd

package
v0.12.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 20, 2026 License: AGPL-3.0 Imports: 36 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrListenerConfig = errors.New("clawkerd listener: config error")

ErrListenerConfig wraps deterministic pre-Serve failures (nil thunk wiring bug, malformed bootstrap material) so main() can map them to exit code 2 (config) instead of the generic 1 (transient). Without this discriminator, a `restart: on-failure:max-retries=N` container would restart-loop forever on a deterministic config bug instead of trip-and-stop on the first failure.

Functions

func NewProgressReporter

func NewProgressReporter(out io.Writer) *progressReporter

NewProgressReporter returns a reporter that writes to out. TTY detection probes TIOCGPGRP — same shape used by spawn_unix.go's stdinCttyFd, portable across the unix targets clawkerd builds for (TCGETS would be linux-only). progress.go has no //go:build unix tag itself, but importing golang.org/x/sys/unix unconditionally fences this file to unix in practice, matching clawkerd's linux-only deployment. On a non-TTY out, ANSI color codes are suppressed and the info icon falls back to "[info]" so log scrapes stay clean.

func NewRegisterCoordinator

func NewRegisterCoordinator(boot *bootstrap, hydraURL, agentAddr, agentName, project string) *registerCoordinator

func NewSpawnState

func NewSpawnState(log *logger.Logger) *spawnState

NewSpawnState returns a spawnState ready to receive Run.

func PasswdGroupPaths

func PasswdGroupPaths() (passwd, group string)

PasswdGroupPaths returns the production passwd/group file paths. Wrapping them in a function gives clawkercp.go a single seam for path injection without touching ResolveUser's signature.

func ReadBootstrap

func ReadBootstrap(dir string) (*bootstrap, error)

ReadBootstrap reads the four bootstrap files from dir. Missing files fail loudly — a partial boot is a security regression (e.g. cert missing would let clawkerd proceed without the cert pinning that defends against tmpfs swap).

func StartClawkerdListener

func StartClawkerdListener(boot *bootstrap, register *registerCoordinator, spawnEntry func() error, onFatal func(error), log *logger.Logger, progress *progressReporter, requestExit func(int), state agentState) (*grpc.Server, error)

StartClawkerdListener binds the ClawkerdService listener on consts.DefaultClawkerdPort, registers the server impl, and starts grpc.Serve in a goroutine. mTLS is required and the peer cert's CN is pinned to consts.ContainerCP — sole legitimate caller is the CP. Without this pin, any other clawker-CA-signed cert (e.g. another agent's) would be accepted and could dispatch root-level ShellCommands (agent-to-agent privilege escalation).

spawnEntry is the AgentReady spawn-trigger thunk passed in as a non-optional dependency: handleAgentReady invokes it to fork the user CMD. nil is rejected at call time so a wiring bug fails loud here rather than at first AgentReady.

onFatal is invoked when grpc.Serve returns a non-stop error (Serve goroutine dead, no further commands can dispatch). main() wires it to a dedicated listenerFatalCh channel so the daemon exits cleanly rather than hanging on ctx.Done with a bricked listener. nil onFatal is rejected: a missing wiring would silently strand the daemon.

Returns the running grpc.Server so main can Stop on shutdown. The underlying net.Listener is owned by the goroutine that runs Serve and is closed by Stop.

Types

type ExecUser

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

ExecUser is the resolved identity material clawkerd hands to the spawn path when starting the user CMD. Fields are unexported so ResolveUser is the sole producer — direct struct literals like `&ExecUser{}` (UID=0, silently re-introducing root) are not representable. Pure data — no syscalls performed here; privilege drop happens in the child via SysProcAttr.Credential between fork and execve.

func ResolveUser

func ResolveUser(spec, passwdPath, groupPath string) (*ExecUser, error)

ResolveUser parses spec ("name", "name:group", "uid", "uid:gid") against the passwd/group databases at the given paths. Production callers pass "/etc/passwd" and "/etc/group" (returned by PasswdGroupPaths()); tests pass synthetic temp files.

/etc/passwd is read ONCE into a byte slice so GetExecUser and the follow-up uid→name lookup operate on the same snapshot. A two-read approach risks identity drift if the file is rewritten between reads (admin tooling, package install) — uid/gid would come from snapshot 1 and Name from snapshot 2. Single-read closes the race.

File errors are surfaced explicitly. moby/sys/user.GetExecUserPath silently ignores open failures and passes a nil reader, which would turn "passwd file missing" into "user not found" — a misleading diagnostic.

func (*ExecUser) GID

func (u *ExecUser) GID() uint32

func (*ExecUser) Groups

func (u *ExecUser) Groups() []uint32

Groups returns a copy of the supplementary group set so callers cannot mutate the resolved identity material.

func (*ExecUser) Home

func (u *ExecUser) Home() string

func (*ExecUser) Name

func (u *ExecUser) Name() string

Name returns the resolved username (matching the uid's /etc/passwd row). Used to set USER and LOGNAME in the child env so tools like npm or sshd see the dropped-privilege identity instead of "root" inherited from PID 1.

func (*ExecUser) UID

func (u *ExecUser) UID() uint32

Directories

Path Synopsis
Package clawkerdembed embeds the per-container agent daemon binary into the clawker CLI release.
Package clawkerdembed embeds the per-container agent daemon binary into the clawker CLI release.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL