The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
// Package osuser resolves local accounts in a way that survives a directory service.
//
// Beacon ships CGO_ENABLED=0, which is what makes every binary statically linked with no glibc
// version floor -- the property that lets it run on a stripped or older userland. The same flag
// selects Go's pure-Go os/user, and that implementation parses /etc/passwd directly and never
// consults NSS. On a host whose accounts come from OpenLDAP, SSSD, or AD, `user.Lookup("alice")`
// therefore fails for an account the rest of the system resolves perfectly well.
//
// That combination is not avoidable by building with cgo: glibc implements NSS by dlopen-ing
// libnss_*.so at runtime, so a statically linked glibc binary cannot consult NSS either. Static
// linking and NSS are mutually exclusive by construction. Shelling out to getent is the standard
// way out, and it keeps the static binaries intact.
//
// The distinction that matters: looking up *yourself* already works, because Go short-circuits a
// by-name lookup to Current() when the name matches, and Current() falls back to $USER/$HOME. It
// is looking up *someone else* -- which is exactly what a root-run system install must do to know
// whose agent runtime to configure -- that fails.
package osuser
import (
"context"
"fmt"
"os/exec"
"os/user"
"strconv"
"strings"
"time"
)
// lookupTimeout bounds the NSS query.
//
// This runs inside a package postinstall, and a directory service that is slow or unreachable is
// an ordinary condition rather than an exotic one. Without a bound, `apt install` would hang on a
// network problem that has nothing to do with Beacon. Treating a timeout as "unresolved" is right:
// the caller already handles an unresolvable user, and failing the whole install over it would be
// worse than configuring nobody.
const lookupTimeout = 5 * time.Second
// Info is the subset of an account Beacon needs: who they are, and where their configuration goes.
type Info struct {
Username string
UID int
GID int
HomeDir string
}
// runGetent is a var so tests can exercise the parsing and the failure modes without depending on
// the host's account database, which is the one thing a test cannot arrange portably.
var runGetent = func(ctx context.Context, name string) (string, error) {
// Resolved explicitly so a missing getent is reported as "no NSS available" rather than as an
// opaque exec failure, and so the absence is distinguishable from a lookup miss.
path, err := exec.LookPath("getent")
if err != nil {
return "", fmt.Errorf("getent is not available: %w", err)
}
// argv, never a shell: the name arrives from SUDO_USER or logind, and passing it as a single
// argument means no quoting scheme has to be correct for it to be safe.
out, err := exec.CommandContext(ctx, path, "passwd", name).Output()
return string(out), err
}
// Lookup resolves a username, consulting NSS when the local account database cannot answer.
//
// The ladder is ordered by cost and certainty: the local database first, since it is in-process
// and covers every ordinary host, then NSS. A caller that also has a home directory to fall back
// on should do so only after this returns an error.
func Lookup(name string) (Info, error) {
name = strings.TrimSpace(name)
if name == "" {
return Info{}, fmt.Errorf("no username given")
}
if u, err := user.Lookup(name); err == nil {
info, convErr := fromUser(u)
if convErr == nil {
return info, nil
}
// A resolvable account with an unparseable uid is a broken database rather than a missing
// user, but NSS may still have a usable answer, so fall through rather than fail here.
}
ctx, cancel := context.WithTimeout(context.Background(), lookupTimeout)
defer cancel()
out, err := runGetent(ctx, name)
if err != nil {
return Info{}, fmt.Errorf("%q is not in the local account database and NSS could not resolve it: %w", name, err)
}
return parseAccountRecord(out, name)
}
func fromUser(u *user.User) (Info, error) {
uid, err := strconv.Atoi(u.Uid)
if err != nil {
return Info{}, fmt.Errorf("uid %q is not numeric: %w", u.Uid, err)
}
gid, err := strconv.Atoi(u.Gid)
if err != nil {
return Info{}, fmt.Errorf("gid %q is not numeric: %w", u.Gid, err)
}
return Info{Username: u.Username, UID: uid, GID: gid, HomeDir: u.HomeDir}, nil
}
// parseAccountRecord reads one account record from getent: name:passwd:uid:gid:gecos:home:shell.
//
// Named for the record rather than for the database it is queried from, because the password
// field is the one field this never reads: on every modern system it holds "x" and the hash lives
// in a shadow file getent does not expose. Fields 0, 2, 3, and 5 -- name, uid, gid, home -- are
// the whole of what is taken, and only the home directory travels any further than this package.
// The earlier name carried "passwd" into an identifier, which static analysis reads as a source
// of password material; every identity hash the resolved home directory reaches then looks like a
// password digest. See the comment on hashString in internal/endpoint/inventory.
//
// getent returns at most one record for a name query, but the output is scanned line by line
// anyway so a trailing newline or a stray banner cannot turn a good answer into a parse failure.
func parseAccountRecord(out, want string) (Info, error) {
for _, line := range strings.Split(out, "\n") {
line = strings.TrimRight(line, "\r")
if strings.TrimSpace(line) == "" {
continue
}
fields := strings.Split(line, ":")
if len(fields) < 7 {
continue
}
uid, err := strconv.Atoi(fields[2])
if err != nil {
continue
}
gid, err := strconv.Atoi(fields[3])
if err != nil {
continue
}
if fields[0] == "" || fields[5] == "" {
continue
}
// The record's own name is preferred over the requested spelling: a directory service may
// answer a differently-cased query with the account's canonical name, and the canonical one
// is what ownership and re-execution should use.
return Info{Username: fields[0], UID: uid, GID: gid, HomeDir: fields[5]}, nil
}
return Info{}, fmt.Errorf("no usable account record for %q", want)
}
// GroupIDs are the groups of the account with uid, its primary group first, as the system's id(1)
// reports them: id consults NSS and macOS's directory service, which the CGO-free os/user never
// does. They are the groups a process run as that account should carry, as the kernel's 32-bit
// ids.
func GroupIDs(uid int) ([]uint32, error) {
ctx, cancel := context.WithTimeout(context.Background(), lookupTimeout)
defer cancel()
out, err := runID(ctx, uid)
if err != nil {
return nil, fmt.Errorf("id -G %d: %w", uid, err)
}
var gids []uint32
for _, field := range strings.Fields(out) {
gid, err := strconv.ParseUint(field, 10, 32)
if err != nil {
return nil, fmt.Errorf("id -G %d printed %q", uid, strings.TrimSpace(out))
}
gids = append(gids, uint32(gid))
}
if len(gids) == 0 {
return nil, fmt.Errorf("id -G %d printed no groups", uid)
}
return gids, nil
}
// runID is a var for the same reason runGetent is.
var runID = func(ctx context.Context, uid int) (string, error) {
path, err := exec.LookPath("id")
if err != nil {
return "", fmt.Errorf("id is not available: %w", err)
}
out, err := exec.CommandContext(ctx, path, "-G", strconv.Itoa(uid)).Output()
return string(out), err
}