childenv

package
v3.1.0-dev.3 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package childenv keeps the daemon's own credentials out of the processes it starts.

The attach bearer token is the credential that answers the agent's permission prompts. Inherited by the bash tool, it let the agent approve its own pending prompt, add a standing allow rule, or reset a tripped guardrail — not by a direct curl, which is itself a gated and visible call, but by test code it wrote and an approved `go test` then ran (#1157). An alert target's bearer_env, inherited the same way, let it post to the target as the daemon.

Two things are needed and neither is sufficient alone:

  • Environ returns the parent environment with every withheld name removed. Every exec site the daemon owns — the bash tool, hooks, MCP stdio servers, sciontool — builds its child's environment from it instead of inheriting.
  • Protect makes the daemon non-dumpable. Without it the first item is cosmetic: /proc/<pid>/environ is the kernel's copy of the environment the process was STARTED with, unaffected by anything the process does to its own environment afterwards, and readable by any same-uid process — so `cat /proc/$PPID/environ` from a scrubbed child recovers the token verbatim. That was measured, not assumed, before this package was written.

What neither can close: an ANCESTOR's environment. A daemon started from a shell that exported the token leaves the token in that shell's /proc/<pid>/environ, which the agent can read just as well and which nothing in this process controls. In a container the daemon is PID 1 and has no such ancestor; on a workstation, pass the token into the daemon's environment only (`TOKEN=… core-agent …`), not by `export`.

The withheld set is process-global because the environment is.

Index

Constants

View Source
const MaxSecretFileBytes = 64 << 10

MaxSecretFileBytes caps how much TakeFile reads. A bearer token is tens of bytes; anything near this size is the wrong file (a PEM bundle, a users table, /dev/zero), and an unbounded read of a device or a pipe nobody closes would hang startup instead of failing it.

View Source
const Supported = true

Supported reports whether Protect does anything on this platform.

Variables

This section is empty.

Functions

func Environ

func Environ() []string

Environ returns os.Environ() minus every withheld name. It always returns a non-nil slice, so assigning it to exec.Cmd.Env never falls back to inheriting the full environment — a nil Env does exactly that, and an empty parent environment would otherwise produce one.

func HoldsCredential

func HoldsCredential() bool

HoldsCredential reports whether any withheld name is actually set in this process's environment — the condition under which Protect is worth its cost.

func IsWithheld

func IsWithheld(name string) bool

IsWithheld reports whether name is in the withheld set. Interpolation consults it: `${env:NAME}` splices a value into text the model reads, which is a more direct route to the model than any child process.

func MayBlock

func MayBlock(path string) bool

MayBlock reports whether reading path can wait indefinitely: anything that is not a regular file — a FIFO with no writer, or a writer that never closes, blocks the open or the read. Callers print a line first, so a startup that is waiting on its token says so instead of hanging silently. A path that cannot be stat'ed reports false; the read that follows produces the error.

func Protect

func Protect() error

Protect clears the process's dumpable flag (prctl PR_SET_DUMPABLE 0).

That is the kernel's switch for "may a same-uid, unprivileged process inspect me": with it cleared, /proc/<pid>/environ and /proc/<pid>/mem fail with EACCES and ptrace attach is refused, for every process without CAP_SYS_PTRACE — which is every process the bash tool starts unless the daemon itself runs as root with full capabilities, in which case its children typically inherit CAP_SYS_PTRACE and this protects nothing (PtraceWarning is the startup check for that, #1201). Children are unaffected: the flag is reset to dumpable on execve, so nothing the agent runs is restricted by it.

The costs, which is why cmd/core-agent calls it only when a withheld credential is actually set (HoldsCredential): no core dumps, and a same-user debugger cannot attach to a running daemon (launching it under the debugger still works, since tracing is established first).

func PtraceWarning

func PtraceWarning(holds, root bool, caps PtraceCaps, capsErr error) string

PtraceWarning returns the startup warning for a daemon whose children can read its memory and /proc entries despite Protect (#1201 item 5), or "" when there is nothing to warn about.

holds is whether the daemon holds a credential worth protecting — a withheld env var that is set, or a configured credential file. root is whether its real or effective uid is 0. caps and capsErr are ReadPtraceCaps' result. The function is pure so every arm is testable without root.

It warns rather than refuses on purpose; see docs/credential-files-design.md ("Settled decisions").

func ReadSecretFile

func ReadSecretFile(path string) (string, error)

ReadSecretFile is TakeFile without the Protect step, for callers that manage hardening themselves and for tests that must not make the shared test process non-dumpable.

func ResolveLenient

func ResolveLenient(abs string) (string, error)

ResolveLenient is resolveLenient for pkg/permissions' ResolvePath.

func Take

func Take(name string) (string, error)

Take is the client-side counterpart, for a process that reads a secret from its environment once and never needs the variable again — an attach client's bearer token, a test receiver's ingress token. It returns the value, unsets the variable so this process's own children (an $EDITOR, a clipboard helper) do not inherit it, and, when the value was set, makes the process non-dumpable so a same-user process cannot read it back out of /proc/<pid>/environ, which Unsetenv does not change (#1201).

The error is Protect's, and the value is returned either way: failing to harden is a reason to warn, not to refuse to authenticate.

func TakeFile

func TakeFile(path string) (value string, protectErr, err error)

TakeFile is Take for a secret held in a file rather than an env var (#1201). It reads the file once, validates it, and — when it holds a value — makes the process non-dumpable, because the value now lives in this process's memory, which a same-user process can otherwise read through /proc/<pid>/mem the same way it reads /proc/<pid>/environ.

A token read from a file never sits in any process's environment: not this one's, not a child's, and not the shell that started this one. A FIFO or a bash process substitution (`--token-file <(pass show x)`) goes further: the value is consumed by the read and there is nothing left on disk for anyone to read afterwards. A regular file stays where it is — TakeFile never deletes it — so it is only out of the agent's reach if the agent cannot read that path.

Rules, each of which turns a mistake into a startup error instead of a bare 401 later:

  • A regular file with any "other" permission bit, or group write, is refused (see insecureFileBits). Pipes, character devices and sockets are not mode-checked: /dev/fd/N from a process substitution is a pipe, and its mode says nothing about who can read it.
  • Surrounding whitespace, including the trailing newline every editor and `echo` adds, is trimmed. What remains must be non-empty and contain no whitespace or control characters: a bearer token has none (RFC 6750 b64token), and a file with several lines is a different file.
  • More than MaxSecretFileBytes is refused.

err is a read or validation failure, and value is then empty. protectErr is Protect's, and value is returned alongside it: failing to harden is a reason to warn, not to refuse to authenticate — the same contract as Take. They are separate results so a caller cannot turn a hardening failure into an outage by checking one error.

func Withheld

func Withheld() []string

Withheld returns the withheld names, sorted, for startup reporting.

func WithheldFile

func WithheldFile(path string) bool

WithheldFile reports whether path names a file in the process-wide credential-file set.

func WithheldFiles

func WithheldFiles() []string

WithheldFiles returns the process-wide credential files, sorted.

func Withhold

func Withhold(names ...string)

Withhold adds env var names to the set no child process inherits. Empty names are ignored, so callers can pass optional config fields straight through. Safe for concurrent use; there is no way to un- withhold a name, because nothing should need one.

func WithholdFiles

func WithholdFiles(paths ...string)

WithholdFiles adds paths to the process-wide credential-file set.

Types

type FileSet

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

FileSet is a set of credential files, matched by path and by inode (#1201). It is the file-shaped counterpart of the withheld env set: files the daemon reads a caller credential from, which nothing the agent drives may read.

A path matches an entry when its lexical absolute form equals the entry's (or the entry's symlink-resolved form at Add), or when it names the same file the entry names NOW: os.Stat on both (which follows symlinks) and os.SameFile. Comparing the current inode is what keeps a Kubernetes Secret volume covered after an update: kubelet re-points users.json's symlink chain at a fresh directory, so any path or inode recorded at boot goes stale, and a caller that resolves symlinks before asking — as the file tools do — would otherwise walk straight past. It also catches a symlink or a hard link to the entry under another name, with no symlink resolution of its own.

No inode is remembered from Add. A remembered inode outlives its file: once the entry is replaced or deleted, the kernel reuses the number, and an unrelated new file would be refused. (Observed in this package's own test run before it was removed.)

The zero value is an empty, usable set. Safe for concurrent use.

func (*FileSet) Add

func (s *FileSet) Add(paths ...string)

Add puts paths in the set. Empty paths are ignored, so callers can pass optional config fields straight through; relative paths resolve against the process working directory, the one the daemon opens them from. There is no way to remove a path.

func (*FileSet) Match

func (s *FileSet) Match(path string) (string, bool)

Match reports whether path names an entry, and which (by its absolute path). The file I/O happens outside the lock.

func (*FileSet) Paths

func (s *FileSet) Paths() []string

Paths returns the entries' absolute paths, sorted.

func (*FileSet) Spellings

func (s *FileSet) Spellings(wd string) map[string][]string

Spellings returns, for each entry, the ways a shell command run in wd can name it directly: its absolute path, its symlink-resolved path, and its path relative to wd when it sits under wd. Keyed by the entry's absolute path.

type PtraceCaps

type PtraceCaps struct {
	Bounding    bool // CAP_SYS_PTRACE is in the bounding set
	Inheritable bool // CAP_SYS_PTRACE is in the inheritable set
	Ambient     bool // CAP_SYS_PTRACE is in the ambient set
}

PtraceCaps is where CAP_SYS_PTRACE sits in this process's capability sets, as far as it decides what the processes it starts will hold.

Protect's guarantee is "no process without CAP_SYS_PTRACE can read me". Whether the agent's children have that capability is decided at execve (capabilities(7)). When the parent's real or effective uid is 0, the kernel treats the new program as carrying every file capability, so the child's permitted set is the parent's inheritable set OR its bounding set (OR ambient). For any parent, the ambient set passes through. Those are the three fields here. The daemon's own effective set does not reach a non-root child, so it is not read.

func ReadPtraceCaps

func ReadPtraceCaps() (PtraceCaps, error)

ReadPtraceCaps reports where CAP_SYS_PTRACE sits in this process's bounding, inheritable and ambient sets.

prctl(PR_CAPBSET_READ) returns 1 when the capability is in the calling thread's bounding set, 0 when not. capget(2) with _LINUX_CAPABILITY_VERSION_3 fills two CapUserData words; capability 19 is in the first. Both are per thread, but nothing in core-agent changes them, so every thread carries the sets the process started with. An error from either is returned: a root daemon whose sets cannot be read gets the warning in its "could not read" form rather than silence.

PR_CAP_AMBIENT_IS_SET fails with EINVAL on kernels before 4.3, which have no ambient set at all, so its error means "not set".

Jump to

Keyboard shortcuts

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