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
- func Environ() []string
- func HoldsCredential() bool
- func IsWithheld(name string) bool
- func MayBlock(path string) bool
- func Protect() error
- func PtraceWarning(holds, root bool, caps PtraceCaps, capsErr error) string
- func ReadSecretFile(path string) (string, error)
- func ResolveLenient(abs string) (string, error)
- func Take(name string) (string, error)
- func TakeFile(path string) (value string, protectErr, err error)
- func Withheld() []string
- func WithheldFile(path string) bool
- func WithheldFiles() []string
- func Withhold(names ...string)
- func WithholdFiles(paths ...string)
- type FileSet
- type PtraceCaps
Constants ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
ResolveLenient is resolveLenient for pkg/permissions' ResolvePath.
func Take ¶
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 ¶
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 ¶
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 ¶
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 ¶
Match reports whether path names an entry, and which (by its absolute path). The file I/O happens outside the lock.
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".