WIP

client/internal/ipcauth/creds_stub.go

@@ -0,0 +1,13 @@
+//go:build !linux && !darwin && !freebsd && !windows
+
+package ipcauth
+
+import "google.golang.org/grpc/credentials"
+
+// NewTransportCredentials returns nil on platforms without a peer-identity
+// primitive. The daemon falls back to insecure credentials and skips per-RPC
+// authorization (logging a warning), preserving pre-hardening behavior until
+// the transport gains an identity primitive.
+func NewTransportCredentials() credentials.TransportCredentials {
+	return nil
+}

client/internal/ipcauth/creds_unix.go

@@ -0,0 +1,48 @@
+//go:build linux || darwin || freebsd
+
+package ipcauth
+
+import (
+	"context"
+	"net"
+
+	"google.golang.org/grpc/credentials"
+)
+
+// NewTransportCredentials returns gRPC transport credentials that extract the
+// caller's kernel-authenticated identity from a Unix-socket connection and
+// expose it via IdentityFromContext. It is non-nil on platforms with a
+// peer-credential primitive.
+func NewTransportCredentials() credentials.TransportCredentials {
+	return unixCreds{}
+}
+
+// unixCreds implements credentials.TransportCredentials over a Unix socket.
+// The server side reads SO_PEERCRED/LOCAL_PEERCRED during the handshake; the
+// client side is a no-op (the kernel supplies the peer identity to the server
+// without any client cooperation).
+type unixCreds struct{}
+
+func (unixCreds) ClientHandshake(_ context.Context, _ string, conn net.Conn) (net.Conn, credentials.AuthInfo, error) {
+	return conn, AuthInfo{}, nil
+}
+
+// ServerHandshake extracts the peer identity and fails closed if it cannot be read.
+func (unixCreds) ServerHandshake(conn net.Conn) (net.Conn, credentials.AuthInfo, error) {
+	id, err := PeerIdentity(conn)
+	if err != nil {
+		return nil, nil, err
+	}
+	return conn, AuthInfo{
+		CommonAuthInfo: credentials.CommonAuthInfo{SecurityLevel: credentials.NoSecurity},
+		Identity:       id,
+	}, nil
+}
+
+func (unixCreds) Info() credentials.ProtocolInfo {
+	return credentials.ProtocolInfo{SecurityProtocol: "netbird-ipc-peercred"}
+}
+
+func (unixCreds) Clone() credentials.TransportCredentials { return unixCreds{} }
+
+func (unixCreds) OverrideServerName(string) error { return nil }

client/internal/ipcauth/creds_windows.go

@@ -0,0 +1,142 @@
+//go:build windows
+
+package ipcauth
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"runtime"
+
+	"golang.org/x/sys/windows"
+	"google.golang.org/grpc/credentials"
+)
+
+var (
+	modadvapi32                    = windows.NewLazySystemDLL("advapi32.dll")
+	procImpersonateNamedPipeClient = modadvapi32.NewProc("ImpersonateNamedPipeClient")
+	procRevertToSelf               = modadvapi32.NewProc("RevertToSelf")
+)
+
+// Windows group-SID attribute flags (winnt.h): a group only counts toward
+// membership when it is enabled and not marked use-for-deny-only.
+const (
+	seGroupEnabled        = 0x00000004
+	seGroupUseForDenyOnly = 0x00000010
+)
+
+// DefaultPipeSDDL restricts the daemon control pipe to LocalSystem (SY), the
+// Administrators group (BA), and interactive logon users (IU). It deliberately
+// excludes Authenticated Users / Everyone so remote or arbitrary service
+// principals cannot connect. This is the Layer-1 channel gate; the interceptor
+// (Layer 2) further restricts by per-profile ownership.
+func DefaultPipeSDDL() string {
+	return "D:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;IU)"
+}
+
+// NewTransportCredentials returns gRPC transport credentials that derive the
+// caller's identity from the named-pipe client token, following Microsoft's
+// "Verifying Client Access with ACLs" pattern: ImpersonateNamedPipeClient ->
+// OpenThreadToken -> RevertToSelf. Per threat-model M-NOIMP, impersonation is
+// used only to read the client token for identity, never to perform privileged work.
+func NewTransportCredentials() credentials.TransportCredentials {
+	return winpipeCreds{}
+}
+
+type winpipeCreds struct{}
+
+func (winpipeCreds) ClientHandshake(_ context.Context, _ string, conn net.Conn) (net.Conn, credentials.AuthInfo, error) {
+	return conn, AuthInfo{}, nil
+}
+
+// ServerHandshake extracts the connecting client's identity from the pipe token.
+// Fails closed if the handle or token cannot be read.
+func (winpipeCreds) ServerHandshake(conn net.Conn) (net.Conn, credentials.AuthInfo, error) {
+	// go-winio's pipe connection embeds *win32File, which exposes Fd().
+	fdConn, ok := conn.(interface{ Fd() uintptr })
+	if !ok {
+		return nil, nil, fmt.Errorf("connection %T does not expose a pipe handle", conn)
+	}
+	handle := windows.Handle(fdConn.Fd())
+
+	id, err := pipeClientIdentity(handle)
+	if err != nil {
+		return nil, nil, err
+	}
+	return conn, AuthInfo{
+		CommonAuthInfo: credentials.CommonAuthInfo{SecurityLevel: credentials.NoSecurity},
+		Identity:       id,
+	}, nil
+}
+
+func (winpipeCreds) Info() credentials.ProtocolInfo {
+	return credentials.ProtocolInfo{SecurityProtocol: "netbird-ipc-peercred"}
+}
+
+func (winpipeCreds) Clone() credentials.TransportCredentials { return winpipeCreds{} }
+
+func (winpipeCreds) OverrideServerName(string) error { return nil }
+
+// pipeClientIdentity reads the connecting client's user SID and enabled group
+// SIDs from the named-pipe handle. The impersonation window is kept as small as
+// possible and pinned to the OS thread (impersonation is thread-local).
+func pipeClientIdentity(handle windows.Handle) (Identity, error) {
+	var pid uint32
+	hasPID := windows.GetNamedPipeClientProcessId(handle, &pid) == nil
+
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+
+	if err := impersonateNamedPipeClient(handle); err != nil {
+		return Identity{}, fmt.Errorf("impersonate named pipe client: %w", err)
+	}
+	defer func() { _ = revertToSelf() }()
+
+	// openAsSelf=true: the token is opened using the daemon's process context
+	// (LocalSystem), not the impersonated client's, so the open always succeeds.
+	var token windows.Token
+	if err := windows.OpenThreadToken(windows.CurrentThread(), windows.TOKEN_QUERY, true, &token); err != nil {
+		return Identity{}, fmt.Errorf("open thread token: %w", err)
+	}
+	defer token.Close()
+
+	tu, err := token.GetTokenUser()
+	if err != nil {
+		return Identity{}, fmt.Errorf("get token user: %w", err)
+	}
+
+	tg, err := token.GetTokenGroups()
+	if err != nil {
+		return Identity{}, fmt.Errorf("get token groups: %w", err)
+	}
+	var groups []string
+	for _, g := range tg.AllGroups() {
+		if g.Attributes&seGroupEnabled == 0 || g.Attributes&seGroupUseForDenyOnly != 0 {
+			continue
+		}
+		groups = append(groups, g.Sid.String())
+	}
+
+	return Identity{
+		SID:    tu.User.Sid.String(),
+		Groups: groups,
+		PID:    int32(pid),
+		HasPID: hasPID,
+	}, nil
+}
+
+func impersonateNamedPipeClient(h windows.Handle) error {
+	r, _, e := procImpersonateNamedPipeClient.Call(uintptr(h))
+	if r == 0 {
+		return e
+	}
+	return nil
+}
+
+func revertToSelf() error {
+	r, _, e := procRevertToSelf.Call()
+	if r == 0 {
+		return e
+	}
+	return nil
+}

client/internal/ipcauth/identity.go

@@ -0,0 +1,93 @@
+// Package ipcauth provides kernel-authenticated caller identity for the daemon's
+// local IPC (gRPC) channel and the transport credentials that populate it.
+//
+// It is the identity foundation shared by two layers of the local-IPC hardening:
+//   - the socket-permission layer (Layer 1, client/cmd), which reads the peer
+//     identity to gate who may connect and to run trust-on-first-use; and
+//   - the per-RPC authorization interceptor (Layer 2), which reads the same
+//     identity from the gRPC context to enforce per-profile ownership.
+//
+// On Unix the identity is read from the kernel via SO_PEERCRED (Linux) or
+// LOCAL_PEERCRED (Darwin/FreeBSD). On Windows it is derived from the named-pipe
+// client token. Platforms without a peer-identity primitive get no credentials
+// and therefore no enforcement (the daemon logs a warning and stays open,
+// preserving today's behavior until the transport is hardened).
+package ipcauth
+
+import (
+	"context"
+	"fmt"
+
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/peer"
+)
+
+// Identity is the kernel-authenticated identity of a local IPC caller.
+//
+// The zero value is not a valid identity; callers obtain one via
+// IdentityFromContext (which reports presence) or PeerIdentity.
+type Identity struct {
+	// UID and GID are the caller's Unix user ID and primary group ID.
+	// Zero on Windows, where SID is authoritative instead.
+	UID uint32
+	GID uint32
+
+	// PID is the caller's process ID, for audit only. HasPID is false when the
+	// platform cannot supply it (e.g. Darwin/FreeBSD xucred carries no PID).
+	PID    int32
+	HasPID bool
+
+	// SID is the caller's Windows security identifier (empty on Unix).
+	SID string
+
+	// Groups holds the caller's Windows group SIDs, captured from the client
+	// token at handshake time (empty on Unix, where supplementary group
+	// membership is resolved on demand via NSS/getent by the authorizer).
+	Groups []string
+}
+
+// IsWindows reports whether this identity is a Windows principal (SID-based)
+// rather than a Unix uid/gid principal.
+func (i Identity) IsWindows() bool {
+	return i.SID != ""
+}
+
+// String renders the identity for audit logs.
+func (i Identity) String() string {
+	if i.IsWindows() {
+		if i.HasPID {
+			return fmt.Sprintf("sid=%s pid=%d", i.SID, i.PID)
+		}
+		return fmt.Sprintf("sid=%s", i.SID)
+	}
+	if i.HasPID {
+		return fmt.Sprintf("uid=%d gid=%d pid=%d", i.UID, i.GID, i.PID)
+	}
+	return fmt.Sprintf("uid=%d gid=%d", i.UID, i.GID)
+}
+
+// AuthInfo carries the peer Identity as a gRPC credentials.AuthInfo so the
+// interceptor can retrieve it from the request context via IdentityFromContext.
+type AuthInfo struct {
+	credentials.CommonAuthInfo
+	Identity Identity
+}
+
+// AuthType identifies the authentication scheme.
+func (AuthInfo) AuthType() string { return "netbird-ipc-peercred" }
+
+// IdentityFromContext extracts the caller's kernel-authenticated identity from
+// the gRPC peer context. The second return value is false when no IPC transport
+// credentials were negotiated (e.g. an unsupported platform, or a caller that
+// did not come through the daemon socket) — callers MUST fail closed in that case.
+func IdentityFromContext(ctx context.Context) (Identity, bool) {
+	p, ok := peer.FromContext(ctx)
+	if !ok {
+		return Identity{}, false
+	}
+	info, ok := p.AuthInfo.(AuthInfo)
+	if !ok {
+		return Identity{}, false
+	}
+	return info.Identity, true
+}

client/internal/ipcauth/identity_test.go

@@ -0,0 +1,47 @@
+package ipcauth
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/peer"
+)
+
+func TestIdentityFromContext_NoPeer(t *testing.T) {
+	_, ok := IdentityFromContext(context.Background())
+	assert.False(t, ok, "bare context must report no identity (fail closed)")
+}
+
+func TestIdentityFromContext_WrongAuthInfo(t *testing.T) {
+	ctx := peer.NewContext(context.Background(), &peer.Peer{})
+	_, ok := IdentityFromContext(ctx)
+	assert.False(t, ok, "peer without our AuthInfo must report no identity")
+}
+
+func TestIdentityFromContext_Present(t *testing.T) {
+	want := Identity{UID: 1000, GID: 1000, PID: 4242, HasPID: true}
+	ctx := peer.NewContext(context.Background(), &peer.Peer{
+		AuthInfo: AuthInfo{
+			CommonAuthInfo: credentials.CommonAuthInfo{SecurityLevel: credentials.NoSecurity},
+			Identity:       want,
+		},
+	})
+
+	got, ok := IdentityFromContext(ctx)
+	assert.True(t, ok)
+	assert.Equal(t, want, got)
+}
+
+func TestIdentity_String(t *testing.T) {
+	assert.Equal(t, "uid=1000 gid=1000 pid=42", Identity{UID: 1000, GID: 1000, PID: 42, HasPID: true}.String())
+	assert.Equal(t, "uid=1000 gid=1000", Identity{UID: 1000, GID: 1000}.String())
+	assert.Equal(t, "sid=S-1-5-21-1 pid=42", Identity{SID: "S-1-5-21-1", PID: 42, HasPID: true}.String())
+	assert.Equal(t, "sid=S-1-5-21-1", Identity{SID: "S-1-5-21-1"}.String())
+}
+
+func TestIdentity_IsWindows(t *testing.T) {
+	assert.True(t, Identity{SID: "S-1-5-18"}.IsWindows())
+	assert.False(t, Identity{UID: 0}.IsWindows())
+}

client/internal/ipcauth/peercred_bsd.go

@@ -0,0 +1,43 @@
+//go:build darwin || freebsd
+
+package ipcauth
+
+import (
+	"fmt"
+	"net"
+
+	"golang.org/x/sys/unix"
+)
+
+// PeerIdentity reads the kernel-authenticated identity of the process on the
+// other end of a Unix socket connection via LOCAL_PEERCRED (xucred). xucred
+// carries the uid and group list but no pid, so audit on these platforms is
+// uid/gid-based (HasPID is false); PID via LOCAL_PEERPID is a possible follow-up.
+func PeerIdentity(c net.Conn) (Identity, error) {
+	uc, ok := c.(*net.UnixConn)
+	if !ok {
+		return Identity{}, fmt.Errorf("connection is not a unix socket: %T", c)
+	}
+	raw, err := uc.SyscallConn()
+	if err != nil {
+		return Identity{}, fmt.Errorf("raw conn: %w", err)
+	}
+
+	var cred *unix.Xucred
+	var credErr error
+	if err := raw.Control(func(fd uintptr) {
+		cred, credErr = unix.GetsockoptXucred(int(fd), unix.SOL_LOCAL, unix.LOCAL_PEERCRED)
+	}); err != nil {
+		return Identity{}, fmt.Errorf("getsockopt control: %w", err)
+	}
+	if credErr != nil {
+		return Identity{}, fmt.Errorf("LOCAL_PEERCRED: %w", credErr)
+	}
+
+	id := Identity{UID: cred.Uid}
+	// Groups[0] is the effective (primary) GID; guard against an empty list.
+	if cred.Ngroups > 0 {
+		id.GID = cred.Groups[0]
+	}
+	return id, nil
+}

client/internal/ipcauth/peercred_linux.go

@@ -0,0 +1,43 @@
+//go:build linux
+
+package ipcauth
+
+import (
+	"fmt"
+	"net"
+
+	"golang.org/x/sys/unix"
+)
+
+// PeerIdentity reads the kernel-authenticated identity of the process on the
+// other end of a Unix socket connection via SO_PEERCRED. The credentials are
+// captured by the kernel at connect() time and cannot be spoofed or changed for
+// the life of the connection.
+func PeerIdentity(c net.Conn) (Identity, error) {
+	uc, ok := c.(*net.UnixConn)
+	if !ok {
+		return Identity{}, fmt.Errorf("connection is not a unix socket: %T", c)
+	}
+	raw, err := uc.SyscallConn()
+	if err != nil {
+		return Identity{}, fmt.Errorf("raw conn: %w", err)
+	}
+
+	var cred *unix.Ucred
+	var credErr error
+	if err := raw.Control(func(fd uintptr) {
+		cred, credErr = unix.GetsockoptUcred(int(fd), unix.SOL_SOCKET, unix.SO_PEERCRED)
+	}); err != nil {
+		return Identity{}, fmt.Errorf("getsockopt control: %w", err)
+	}
+	if credErr != nil {
+		return Identity{}, fmt.Errorf("SO_PEERCRED: %w", credErr)
+	}
+
+	return Identity{
+		UID:    cred.Uid,
+		GID:    cred.Gid,
+		PID:    cred.Pid,
+		HasPID: true,
+	}, nil
+}

client/internal/ipcauth/peercred_stub.go

@@ -0,0 +1,16 @@
+//go:build !linux && !darwin && !freebsd
+
+package ipcauth
+
+import (
+	"fmt"
+	"net"
+	"runtime"
+)
+
+// PeerIdentity is unimplemented on platforms without a Unix-socket peer-credential
+// primitive. Windows derives identity from the named-pipe client token instead
+// (see the Windows transport credentials), so it never calls this.
+func PeerIdentity(net.Conn) (Identity, error) {
+	return Identity{}, fmt.Errorf("peer credential check not supported on %s", runtime.GOOS)
+}

client/internal/ipcauth/peercred_unix_test.go

@@ -0,0 +1,113 @@
+//go:build linux || darwin || freebsd
+
+package ipcauth
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestPeerIdentity_MatchesCurrentProcess connects to a real Unix socket and
+// verifies the extracted UID/GID match the running process (both ends are us).
+func TestPeerIdentity_MatchesCurrentProcess(t *testing.T) {
+	sock := filepath.Join(t.TempDir(), "peer.sock")
+	ln, err := net.Listen("unix", sock)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = ln.Close() })
+
+	type result struct {
+		id  Identity
+		err error
+	}
+	done := make(chan result, 1)
+	go func() {
+		c, aerr := ln.Accept()
+		if aerr != nil {
+			done <- result{err: aerr}
+			return
+		}
+		defer func() { _ = c.Close() }()
+		id, ierr := PeerIdentity(c)
+		done <- result{id: id, err: ierr}
+	}()
+
+	client, err := net.Dial("unix", sock)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = client.Close() })
+
+	res := <-done
+	require.NoError(t, res.err)
+	assert.Equal(t, uint32(os.Getuid()), res.id.UID, "UID should match current process")
+	assert.Equal(t, uint32(os.Getgid()), res.id.GID, "primary GID should match current process")
+}
+
+// TestPeerIdentity_NonUnixConn rejects non-Unix connections (fail closed).
+func TestPeerIdentity_NonUnixConn(t *testing.T) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = ln.Close() })
+
+	done := make(chan error, 1)
+	go func() {
+		c, aerr := ln.Accept()
+		if aerr != nil {
+			done <- aerr
+			return
+		}
+		defer func() { _ = c.Close() }()
+		_, ierr := PeerIdentity(c)
+		done <- ierr
+	}()
+
+	client, err := net.Dial("tcp", ln.Addr().String())
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = client.Close() })
+
+	assert.Error(t, <-done, "PeerIdentity must reject a non-Unix connection")
+}
+
+// TestUnixCreds_ServerHandshake exercises the transport-credentials path end to end.
+func TestUnixCreds_ServerHandshake(t *testing.T) {
+	creds := NewTransportCredentials()
+	require.NotNil(t, creds)
+
+	sock := filepath.Join(t.TempDir(), "hs.sock")
+	ln, err := net.Listen("unix", sock)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = ln.Close() })
+
+	type result struct {
+		info interface{ AuthType() string }
+		err  error
+	}
+	done := make(chan result, 1)
+	go func() {
+		c, aerr := ln.Accept()
+		if aerr != nil {
+			done <- result{err: aerr}
+			return
+		}
+		_, ai, herr := creds.ServerHandshake(c)
+		if herr != nil {
+			done <- result{err: herr}
+			return
+		}
+		done <- result{info: ai}
+	}()
+
+	client, err := net.Dial("unix", sock)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = client.Close() })
+
+	res := <-done
+	require.NoError(t, res.err)
+	ai, ok := res.info.(AuthInfo)
+	require.True(t, ok, "expected ipcauth.AuthInfo, got %T", res.info)
+	assert.Equal(t, uint32(os.Getuid()), ai.Identity.UID)
+	assert.Equal(t, "netbird-ipc-peercred", ai.AuthType())
+}

client/internal/shell/getent_cgo_unix.go

@@ -0,0 +1,29 @@
+//go:build cgo && !osusergo && !windows
+
+package shell
+
+import "os/user"
+
+// LookupWithGetent with CGO delegates directly to os/user.Lookup.
+// When CGO is enabled, os/user uses libc (getpwnam_r) which goes through
+// the NSS stack natively. If it fails, the user truly doesn't exist and
+// getent would also fail.
+func LookupWithGetent(username string) (*user.User, error) {
+	return user.Lookup(username)
+}
+
+// CurrentUserWithGetent with CGO delegates directly to os/user.Current.
+func CurrentUserWithGetent() (*user.User, error) {
+	return user.Current()
+}
+
+// LookupGroupWithGetent returns the resolved group from either a gid or groupname.
+func LookupGroupWithGetent(name string) (*user.Group, error) {
+	return user.LookupGroup(name)
+}
+
+// GroupIdsWithFallback with CGO delegates directly to user.GroupIds.
+// libc's getgrouplist handles NSS groups natively.
+func GroupIdsWithFallback(u *user.User) ([]string, error) {
+	return u.GroupIds()
+}

client/internal/shell/getent_nocgo_unix.go

@@ -0,0 +1,92 @@
+//go:build (!cgo || osusergo) && !windows
+
+package shell
+
+import (
+	"os"
+	"os/user"
+	"strconv"
+
+	log "github.com/sirupsen/logrus"
+)
+
+// LookupWithGetent looks up a user by name, falling back to getent if os/user fails.
+// Without CGO, os/user only reads /etc/passwd and misses NSS-provided users.
+// getent goes through the host's NSS stack.
+func LookupWithGetent(username string) (*user.User, error) {
+	u, err := user.Lookup(username)
+	if err == nil {
+		return u, nil
+	}
+
+	stdErr := err
+	log.Debugf("os/user.Lookup(%q) failed, trying getent: %v", username, err)
+
+	u, _, getentErr := runGetentPasswd(username)
+	if getentErr != nil {
+		log.Debugf("getent fallback for %q also failed: %v", username, getentErr)
+		return nil, stdErr
+	}
+
+	return u, nil
+}
+
+// LookupGroupWithGetent returns the resolved group from either a gid or groupname,
+// falling back to getent if os/user fails (NSS groups under nocgo).
+func LookupGroupWithGetent(name string) (*user.Group, error) {
+	g, err := user.LookupGroup(name)
+	if err == nil {
+		return g, nil
+	}
+
+	stdErr := err
+	log.Debugf("os/user.LookupGroup(%q) failed, trying getent: %v", name, err)
+	g, getentErr := runGetentGroup(name)
+	if getentErr != nil {
+		log.Debugf("getent fallback for %q also failed: %v", name, getentErr)
+		return nil, stdErr
+	}
+	return g, nil
+}
+
+// CurrentUserWithGetent gets the current user, falling back to getent if os/user fails.
+func CurrentUserWithGetent() (*user.User, error) {
+	u, err := user.Current()
+	if err == nil {
+		return u, nil
+	}
+
+	stdErr := err
+	uid := strconv.Itoa(os.Getuid())
+	log.Debugf("os/user.Current() failed, trying getent with UID %s: %v", uid, err)
+
+	u, _, getentErr := runGetentPasswd(uid)
+	if getentErr != nil {
+		return nil, stdErr
+	}
+
+	return u, nil
+}
+
+// GroupIdsWithFallback gets group IDs for a user via the id command first,
+// falling back to user.GroupIds().
+// NOTE: unlike LookupWithGetent/CurrentUserWithGetent which try stdlib first,
+// this intentionally tries `id -G` first because without CGO, user.GroupIds()
+// only reads /etc/group and silently returns incomplete results for NSS users
+// (no error, just missing groups). The id command goes through NSS and returns
+// the full set.
+func GroupIdsWithFallback(u *user.User) ([]string, error) {
+	ids, err := runIdGroups(u.Username)
+	if err == nil {
+		return ids, nil
+	}
+
+	log.Debugf("id -G %q failed, falling back to user.GroupIds(): %v", u.Username, err)
+
+	ids, stdErr := u.GroupIds()
+	if stdErr != nil {
+		return nil, stdErr
+	}
+
+	return ids, nil
+}

client/internal/shell/getent_test.go

@@ -0,0 +1,172 @@
+package shell
+
+import (
+	"os/user"
+	"runtime"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLookupWithGetent_CurrentUser(t *testing.T) {
+	// The current user should always be resolvable on any platform
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	u, err := LookupWithGetent(current.Username)
+	require.NoError(t, err)
+	assert.Equal(t, current.Username, u.Username)
+	assert.Equal(t, current.Uid, u.Uid)
+	assert.Equal(t, current.Gid, u.Gid)
+}
+
+func TestLookupWithGetent_NonexistentUser(t *testing.T) {
+	_, err := LookupWithGetent("nonexistent_user_xyzzy_12345")
+	require.Error(t, err, "should fail for nonexistent user")
+}
+
+func TestCurrentUserWithGetent(t *testing.T) {
+	stdUser, err := user.Current()
+	require.NoError(t, err)
+
+	u, err := CurrentUserWithGetent()
+	require.NoError(t, err)
+	assert.Equal(t, stdUser.Uid, u.Uid)
+	assert.Equal(t, stdUser.Username, u.Username)
+}
+
+func TestGroupIdsWithFallback_CurrentUser(t *testing.T) {
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	groups, err := GroupIdsWithFallback(current)
+	require.NoError(t, err)
+	require.NotEmpty(t, groups, "current user should have at least one group")
+
+	if runtime.GOOS != "windows" {
+		for _, gid := range groups {
+			_, err := strconv.ParseUint(gid, 10, 32)
+			assert.NoError(t, err, "group ID %q should be a valid uint32", gid)
+		}
+	}
+}
+
+func TestGetShellFromGetent_CurrentUser(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		// Windows stub always returns empty, which is correct
+		shell := GetShellFromGetent("1000")
+		assert.Empty(t, shell, "Windows stub should return empty")
+		return
+	}
+
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	// getent may not be available on all systems (e.g., macOS without Homebrew getent)
+	shell := GetShellFromGetent(current.Uid)
+	if shell == "" {
+		t.Log("GetShellFromGetent returned empty, getent may not be available")
+		return
+	}
+	assert.True(t, shell[0] == '/', "shell should be an absolute path, got %q", shell)
+}
+
+func TestLookupWithGetent_RootUser(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("no root user on Windows")
+	}
+
+	u, err := LookupWithGetent("root")
+	if err != nil {
+		t.Skip("root user not available on this system")
+	}
+	assert.Equal(t, "0", u.Uid, "root should have UID 0")
+}
+
+// TestIntegration_FullLookupChain exercises the complete user lookup chain
+// against the real system, testing that all wrappers (LookupWithGetent,
+// CurrentUserWithGetent, GroupIdsWithFallback, GetShellFromGetent) produce
+// consistent and correct results when composed together.
+func TestIntegration_FullLookupChain(t *testing.T) {
+	// Step 1: CurrentUserWithGetent must resolve the running user.
+	current, err := CurrentUserWithGetent()
+	require.NoError(t, err, "CurrentUserWithGetent must resolve the running user")
+	require.NotEmpty(t, current.Uid)
+	require.NotEmpty(t, current.Username)
+
+	// Step 2: LookupWithGetent by the same username must return matching identity.
+	byName, err := LookupWithGetent(current.Username)
+	require.NoError(t, err)
+	assert.Equal(t, current.Uid, byName.Uid, "lookup by name should return same UID")
+	assert.Equal(t, current.Gid, byName.Gid, "lookup by name should return same GID")
+	assert.Equal(t, current.HomeDir, byName.HomeDir, "lookup by name should return same home")
+
+	// Step 3: GroupIdsWithFallback must return at least the primary GID.
+	groups, err := GroupIdsWithFallback(current)
+	require.NoError(t, err)
+	require.NotEmpty(t, groups, "user must have at least one group")
+
+	foundPrimary := false
+	for _, gid := range groups {
+		if runtime.GOOS != "windows" {
+			_, err := strconv.ParseUint(gid, 10, 32)
+			require.NoError(t, err, "group ID %q must be a valid uint32", gid)
+		}
+		if gid == current.Gid {
+			foundPrimary = true
+		}
+	}
+	assert.True(t, foundPrimary, "primary GID %s should appear in supplementary groups", current.Gid)
+
+	// Step 4: GetShellFromGetent should either return a valid shell path or empty
+	// (empty is OK when getent is not available, e.g. macOS without Homebrew getent).
+	if runtime.GOOS != "windows" {
+		shell := GetShellFromGetent(current.Uid)
+		if shell != "" {
+			assert.True(t, shell[0] == '/', "shell should be an absolute path, got %q", shell)
+		}
+	}
+}
+
+// TestIntegration_LookupAndGroupsConsistency verifies that a user resolved via
+// LookupWithGetent can have their groups resolved via GroupIdsWithFallback,
+// testing the handoff between the two functions as used by the SSH server.
+func TestIntegration_LookupAndGroupsConsistency(t *testing.T) {
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	// Simulate the SSH server flow: lookup user, then get their groups.
+	resolved, err := LookupWithGetent(current.Username)
+	require.NoError(t, err)
+
+	groups, err := GroupIdsWithFallback(resolved)
+	require.NoError(t, err)
+	require.NotEmpty(t, groups, "resolved user must have groups")
+
+	// On Unix, all returned GIDs must be valid numeric values.
+	// On Windows, group IDs are SIDs (e.g., "S-1-5-32-544").
+	if runtime.GOOS != "windows" {
+		for _, gid := range groups {
+			_, err := strconv.ParseUint(gid, 10, 32)
+			assert.NoError(t, err, "group ID %q should be numeric", gid)
+		}
+	}
+}
+
+// TestIntegration_ShellLookupChain tests the full shell resolution chain
+// (getShellFromPasswd -> GetShellFromGetent -> $SHELL -> default) on Unix.
+func TestIntegration_ShellLookupChain(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Unix shell lookup not applicable on Windows")
+	}
+
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	// GetUserShell is the top-level function used by the SSH server.
+	shell := GetUserShell(current.Uid)
+	require.NotEmpty(t, shell, "GetUserShell must always return a shell")
+	assert.True(t, shell[0] == '/', "shell should be an absolute path, got %q", shell)
+}

client/internal/shell/getent_unix.go

@@ -0,0 +1,165 @@
+//go:build !windows
+
+package shell
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"os/user"
+	"runtime"
+	"strings"
+	"time"
+)
+
+const getentTimeout = 5 * time.Second
+
+// GetShellFromGetent gets a user's login shell via getent by UID.
+// This is needed even with CGO because getShellFromPasswd reads /etc/passwd
+// directly and won't find NSS-provided users there.
+func GetShellFromGetent(userID string) string {
+	_, shell, err := runGetentPasswd(userID)
+	if err != nil {
+		return ""
+	}
+	return shell
+}
+
+// GetUserFromGetent returns the resolved user from either a uid or username,
+// going through the host's NSS stack.
+func GetUserFromGetent(query string) (*user.User, error) {
+	u, _, err := runGetentPasswd(query)
+	return u, err
+}
+
+// runGetentPasswd executes `getent passwd <query>` and returns the user and login shell.
+func runGetentPasswd(query string) (*user.User, string, error) {
+	if !validateGetentInput(query) {
+		return nil, "", fmt.Errorf("invalid getent input: %q", query)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), getentTimeout)
+	defer cancel()
+
+	out, err := exec.CommandContext(ctx, "getent", "passwd", query).Output()
+	if err != nil {
+		return nil, "", fmt.Errorf("getent passwd %s: %w", query, err)
+	}
+
+	return parseGetentPasswd(string(out))
+}
+
+// runGetentGroup executes `getent group <query>` and returns the group.
+func runGetentGroup(query string) (*user.Group, error) {
+	if !validateGetentInput(query) {
+		return nil, fmt.Errorf("invalid getent input: %q", query)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), getentTimeout)
+	defer cancel()
+
+	out, err := exec.CommandContext(ctx, "getent", "group", query).Output()
+	if err != nil {
+		return nil, fmt.Errorf("getent group %s: %w", query, err)
+	}
+
+	return parseGetentGroup(string(out))
+}
+
+// parseGetentPasswd parses getent passwd output: "name:x:uid:gid:gecos:home:shell".
+func parseGetentPasswd(output string) (*user.User, string, error) {
+	fields := strings.SplitN(strings.TrimSpace(output), ":", 8)
+	if len(fields) < 6 {
+		return nil, "", fmt.Errorf("unexpected getent output (need 6+ fields): %q", output)
+	}
+
+	if fields[0] == "" || fields[2] == "" || fields[3] == "" {
+		return nil, "", fmt.Errorf("missing required fields in getent output: %q", output)
+	}
+
+	var shell string
+	if len(fields) >= 7 {
+		shell = fields[6]
+	}
+
+	return &user.User{
+		Username: fields[0],
+		Uid:      fields[2],
+		Gid:      fields[3],
+		Name:     fields[4],
+		HomeDir:  fields[5],
+	}, shell, nil
+}
+
+// parseGetentGroup parses getent group output: "group:x:gid:members".
+func parseGetentGroup(output string) (*user.Group, error) {
+	fields := strings.SplitN(strings.TrimSpace(output), ":", 8)
+	if len(fields) < 4 {
+		return nil, fmt.Errorf("unexpected getent output (need 4+ fields): %q", output)
+	}
+
+	if fields[0] == "" || fields[2] == "" {
+		return nil, fmt.Errorf("missing required fields in getent output: %q", output)
+	}
+
+	return &user.Group{Gid: fields[2], Name: fields[0]}, nil
+}
+
+// validateGetentInput checks that the input is safe to pass to getent or id.
+// Allows POSIX usernames, numeric UIDs, and common NSS extensions
+// (@ for Kerberos, $ for Samba, + for NIS compat). A leading hyphen is
+// rejected so the input can never be parsed as a command-line flag.
+func validateGetentInput(input string) bool {
+	maxLen := 32
+	if runtime.GOOS == "linux" {
+		maxLen = 256
+	}
+
+	if len(input) == 0 || len(input) > maxLen {
+		return false
+	}
+
+	if input[0] == '-' {
+		return false
+	}
+
+	for _, r := range input {
+		if isAllowedGetentChar(r) {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+func isAllowedGetentChar(r rune) bool {
+	if r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' {
+		return true
+	}
+	switch r {
+	case '.', '_', '-', '@', '+', '$':
+		return true
+	}
+	return false
+}
+
+// runIdGroups runs `id -G <username>` and returns the space-separated group IDs.
+func runIdGroups(username string) ([]string, error) {
+	if !validateGetentInput(username) {
+		return nil, fmt.Errorf("invalid username for id command: %q", username)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), getentTimeout)
+	defer cancel()
+
+	out, err := exec.CommandContext(ctx, "id", "-G", username).Output()
+	if err != nil {
+		return nil, fmt.Errorf("id -G %s: %w", username, err)
+	}
+
+	trimmed := strings.TrimSpace(string(out))
+	if trimmed == "" {
+		return nil, fmt.Errorf("id -G %s: empty output", username)
+	}
+	return strings.Fields(trimmed), nil
+}

client/internal/shell/getent_unix_test.go

@@ -0,0 +1,413 @@
+//go:build !windows
+
+package shell
+
+import (
+	"os/exec"
+	"os/user"
+	"runtime"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseGetentPasswd(t *testing.T) {
+	tests := []struct {
+		name        string
+		input       string
+		wantUser    *user.User
+		wantShell   string
+		wantErr     bool
+		errContains string
+	}{
+		{
+			name:  "standard entry",
+			input: "alice:x:1001:1001:Alice Smith:/home/alice:/bin/bash\n",
+			wantUser: &user.User{
+				Username: "alice",
+				Uid:      "1001",
+				Gid:      "1001",
+				Name:     "Alice Smith",
+				HomeDir:  "/home/alice",
+			},
+			wantShell: "/bin/bash",
+		},
+		{
+			name:  "root entry",
+			input: "root:x:0:0:root:/root:/bin/bash",
+			wantUser: &user.User{
+				Username: "root",
+				Uid:      "0",
+				Gid:      "0",
+				Name:     "root",
+				HomeDir:  "/root",
+			},
+			wantShell: "/bin/bash",
+		},
+		{
+			name:  "empty gecos field",
+			input: "svc:x:999:999::/var/lib/svc:/usr/sbin/nologin",
+			wantUser: &user.User{
+				Username: "svc",
+				Uid:      "999",
+				Gid:      "999",
+				Name:     "",
+				HomeDir:  "/var/lib/svc",
+			},
+			wantShell: "/usr/sbin/nologin",
+		},
+		{
+			name:  "gecos with commas",
+			input: "john:x:1002:1002:John Doe,Room 101,555-1234,555-4321:/home/john:/bin/zsh",
+			wantUser: &user.User{
+				Username: "john",
+				Uid:      "1002",
+				Gid:      "1002",
+				Name:     "John Doe,Room 101,555-1234,555-4321",
+				HomeDir:  "/home/john",
+			},
+			wantShell: "/bin/zsh",
+		},
+		{
+			name:  "remote user with large UID",
+			input: "remoteuser:*:50001:50001:Remote User:/home/remoteuser:/bin/bash\n",
+			wantUser: &user.User{
+				Username: "remoteuser",
+				Uid:      "50001",
+				Gid:      "50001",
+				Name:     "Remote User",
+				HomeDir:  "/home/remoteuser",
+			},
+			wantShell: "/bin/bash",
+		},
+		{
+			name:  "no shell field (only 6 fields)",
+			input: "minimal:x:1000:1000::/home/minimal",
+			wantUser: &user.User{
+				Username: "minimal",
+				Uid:      "1000",
+				Gid:      "1000",
+				Name:     "",
+				HomeDir:  "/home/minimal",
+			},
+			wantShell: "",
+		},
+		{
+			name:        "too few fields",
+			input:       "bad:x:1000",
+			wantErr:     true,
+			errContains: "need 6+ fields",
+		},
+		{
+			name:        "empty username",
+			input:       ":x:1000:1000::/home/test:/bin/bash",
+			wantErr:     true,
+			errContains: "missing required fields",
+		},
+		{
+			name:        "empty UID",
+			input:       "test:x::1000::/home/test:/bin/bash",
+			wantErr:     true,
+			errContains: "missing required fields",
+		},
+		{
+			name:        "empty GID",
+			input:       "test:x:1000:::/home/test:/bin/bash",
+			wantErr:     true,
+			errContains: "missing required fields",
+		},
+		{
+			name:        "empty input",
+			input:       "",
+			wantErr:     true,
+			errContains: "need 6+ fields",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			u, shell, err := parseGetentPasswd(tt.input)
+			if tt.wantErr {
+				require.Error(t, err)
+				if tt.errContains != "" {
+					assert.Contains(t, err.Error(), tt.errContains)
+				}
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantUser.Username, u.Username, "username")
+			assert.Equal(t, tt.wantUser.Uid, u.Uid, "UID")
+			assert.Equal(t, tt.wantUser.Gid, u.Gid, "GID")
+			assert.Equal(t, tt.wantUser.Name, u.Name, "name/gecos")
+			assert.Equal(t, tt.wantUser.HomeDir, u.HomeDir, "home directory")
+			assert.Equal(t, tt.wantShell, shell, "shell")
+		})
+	}
+}
+
+func TestValidateGetentInput(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  bool
+	}{
+		{"normal username", "alice", true},
+		{"numeric UID", "1001", true},
+		{"dots and underscores", "alice.bob_test", true},
+		{"hyphen", "alice-bob", true},
+		{"leading hyphen rejected", "-i", false},
+		{"leading double hyphen rejected", "--no-idn", false},
+		{"lone hyphen rejected", "-", false},
+		{"kerberos principal", "user@REALM", true},
+		{"samba machine account", "MACHINE$", true},
+		{"NIS compat", "+user", true},
+		{"empty", "", false},
+		{"null byte", "alice\x00bob", false},
+		{"newline", "alice\nbob", false},
+		{"tab", "alice\tbob", false},
+		{"control char", "alice\x01bob", false},
+		{"DEL char", "alice\x7fbob", false},
+		{"space rejected", "alice bob", false},
+		{"semicolon rejected", "alice;bob", false},
+		{"backtick rejected", "alice`bob", false},
+		{"pipe rejected", "alice|bob", false},
+		{"33 chars exceeds non-linux max", makeLongString(33), runtime.GOOS == "linux"},
+		{"256 chars at linux max", makeLongString(256), runtime.GOOS == "linux"},
+		{"257 chars exceeds all limits", makeLongString(257), false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, validateGetentInput(tt.input))
+		})
+	}
+}
+
+func makeLongString(n int) string {
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = 'a'
+	}
+	return string(b)
+}
+
+func TestRunGetent_RootUser(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err != nil {
+		t.Skip("getent not available on this system")
+	}
+
+	u, shell, err := runGetentPasswd("root")
+	require.NoError(t, err)
+	assert.Equal(t, "root", u.Username)
+	assert.Equal(t, "0", u.Uid)
+	assert.Equal(t, "0", u.Gid)
+	assert.NotEmpty(t, shell, "root should have a shell")
+}
+
+func TestRunGetent_ByUID(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err != nil {
+		t.Skip("getent not available on this system")
+	}
+
+	u, _, err := runGetentPasswd("0")
+	require.NoError(t, err)
+	assert.Equal(t, "root", u.Username)
+	assert.Equal(t, "0", u.Uid)
+}
+
+func TestRunGetent_NonexistentUser(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err != nil {
+		t.Skip("getent not available on this system")
+	}
+
+	_, _, err := runGetentPasswd("nonexistent_user_xyzzy_12345")
+	assert.Error(t, err)
+}
+
+func TestRunGetent_InvalidInput(t *testing.T) {
+	_, _, err := runGetentPasswd("")
+	assert.Error(t, err)
+
+	_, _, err = runGetentPasswd("user\x00name")
+	assert.Error(t, err)
+}
+
+func TestRunGetent_NotAvailable(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err == nil {
+		t.Skip("getent is available, can't test missing case")
+	}
+
+	_, _, err := runGetentPasswd("root")
+	assert.Error(t, err, "should fail when getent is not installed")
+}
+
+func TestRunIdGroups_CurrentUser(t *testing.T) {
+	if _, err := exec.LookPath("id"); err != nil {
+		t.Skip("id not available on this system")
+	}
+
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	groups, err := runIdGroups(current.Username)
+	require.NoError(t, err)
+	require.NotEmpty(t, groups, "current user should have at least one group")
+
+	for _, gid := range groups {
+		_, err := strconv.ParseUint(gid, 10, 32)
+		assert.NoError(t, err, "group ID %q should be a valid uint32", gid)
+	}
+}
+
+func TestRunIdGroups_NonexistentUser(t *testing.T) {
+	if _, err := exec.LookPath("id"); err != nil {
+		t.Skip("id not available on this system")
+	}
+
+	_, err := runIdGroups("nonexistent_user_xyzzy_12345")
+	assert.Error(t, err)
+}
+
+func TestRunIdGroups_InvalidInput(t *testing.T) {
+	_, err := runIdGroups("")
+	assert.Error(t, err)
+
+	_, err = runIdGroups("user\x00name")
+	assert.Error(t, err)
+}
+
+func TestGetentResultsMatchStdlib(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err != nil {
+		t.Skip("getent not available on this system")
+	}
+
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	getentUser, _, err := runGetentPasswd(current.Username)
+	require.NoError(t, err)
+
+	assert.Equal(t, current.Username, getentUser.Username, "username should match")
+	assert.Equal(t, current.Uid, getentUser.Uid, "UID should match")
+	assert.Equal(t, current.Gid, getentUser.Gid, "GID should match")
+	assert.Equal(t, current.HomeDir, getentUser.HomeDir, "home directory should match")
+}
+
+func TestGetentResultsMatchStdlib_ByUID(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err != nil {
+		t.Skip("getent not available on this system")
+	}
+
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	getentUser, _, err := runGetentPasswd(current.Uid)
+	require.NoError(t, err)
+
+	assert.Equal(t, current.Username, getentUser.Username, "username should match when looked up by UID")
+	assert.Equal(t, current.Uid, getentUser.Uid, "UID should match")
+}
+
+func TestIdGroupsMatchStdlib(t *testing.T) {
+	if _, err := exec.LookPath("id"); err != nil {
+		t.Skip("id not available on this system")
+	}
+
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	stdGroups, err := current.GroupIds()
+	if err != nil {
+		t.Skip("os/user.GroupIds() not working, likely CGO_ENABLED=0")
+	}
+
+	idGroups, err := runIdGroups(current.Username)
+	require.NoError(t, err)
+
+	// Deduplicate both lists: id -G can return duplicates (e.g., root in Docker)
+	// and ElementsMatch treats duplicates as distinct.
+	assert.ElementsMatch(t, uniqueStrings(stdGroups), uniqueStrings(idGroups), "id -G should return same groups as os/user")
+}
+
+func uniqueStrings(ss []string) []string {
+	seen := make(map[string]struct{}, len(ss))
+	out := make([]string, 0, len(ss))
+	for _, s := range ss {
+		if _, ok := seen[s]; ok {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+	}
+	return out
+}
+
+// TestGetShellFromPasswd_CurrentUser verifies that getShellFromPasswd correctly
+// reads the current user's shell from /etc/passwd by comparing it against what
+// getent reports (which goes through NSS).
+func TestGetShellFromPasswd_CurrentUser(t *testing.T) {
+	current, err := user.Current()
+	require.NoError(t, err)
+
+	shell := getShellFromPasswd(current.Uid)
+	if shell == "" {
+		t.Skip("current user not found in /etc/passwd (may be an NSS-only user)")
+	}
+
+	assert.True(t, shell[0] == '/', "shell should be an absolute path, got %q", shell)
+
+	if _, err := exec.LookPath("getent"); err == nil {
+		_, getentShell, getentErr := runGetentPasswd(current.Uid)
+		if getentErr == nil && getentShell != "" {
+			assert.Equal(t, getentShell, shell, "shell from /etc/passwd should match getent")
+		}
+	}
+}
+
+// TestGetShellFromPasswd_RootUser verifies that getShellFromPasswd can read
+// root's shell from /etc/passwd. Root is guaranteed to be in /etc/passwd on
+// any standard Unix system.
+func TestGetShellFromPasswd_RootUser(t *testing.T) {
+	shell := getShellFromPasswd("0")
+	require.NotEmpty(t, shell, "root (UID 0) must be in /etc/passwd")
+	assert.True(t, shell[0] == '/', "root shell should be an absolute path, got %q", shell)
+}
+
+// TestGetShellFromPasswd_NonexistentUID verifies that getShellFromPasswd
+// returns empty for a UID that doesn't exist in /etc/passwd.
+func TestGetShellFromPasswd_NonexistentUID(t *testing.T) {
+	shell := getShellFromPasswd("4294967294")
+	assert.Empty(t, shell, "nonexistent UID should return empty shell")
+}
+
+// TestGetShellFromPasswd_MatchesGetentForKnownUsers reads /etc/passwd directly
+// and cross-validates every entry against getent to ensure parseGetentPasswd
+// and getShellFromPasswd agree on shell values.
+func TestGetShellFromPasswd_MatchesGetentForKnownUsers(t *testing.T) {
+	if _, err := exec.LookPath("getent"); err != nil {
+		t.Skip("getent not available")
+	}
+
+	// Pick a few well-known system UIDs that are virtually always in /etc/passwd.
+	uids := []string{"0"} // root
+
+	current, err := user.Current()
+	require.NoError(t, err)
+	uids = append(uids, current.Uid)
+
+	for _, uid := range uids {
+		passwdShell := getShellFromPasswd(uid)
+		if passwdShell == "" {
+			continue
+		}
+
+		_, getentShell, err := runGetentPasswd(uid)
+		if err != nil {
+			continue
+		}
+
+		assert.Equal(t, getentShell, passwdShell, "shell mismatch for UID %s", uid)
+	}
+}

client/internal/shell/getent_windows.go

@@ -0,0 +1,31 @@
+//go:build windows
+
+package shell
+
+import "os/user"
+
+// LookupWithGetent on Windows just delegates to os/user.Lookup.
+// Windows does not use NSS/getent; its user lookup works without CGO.
+func LookupWithGetent(username string) (*user.User, error) {
+	return user.Lookup(username)
+}
+
+// CurrentUserWithGetent on Windows just delegates to os/user.Current.
+func CurrentUserWithGetent() (*user.User, error) {
+	return user.Current()
+}
+
+// LookupGroupWithGetent on Windows just delegates to os/user.LookupGroup.
+func LookupGroupWithGetent(name string) (*user.Group, error) {
+	return user.LookupGroup(name)
+}
+
+// GetShellFromGetent is a no-op on Windows; shell resolution uses PowerShell detection.
+func GetShellFromGetent(_ string) string {
+	return ""
+}
+
+// GroupIdsWithFallback on Windows just delegates to u.GroupIds().
+func GroupIdsWithFallback(u *user.User) ([]string, error) {
+	return u.GroupIds()
+}

client/internal/shell/shell.go

@@ -0,0 +1,155 @@
+package shell
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"os/exec"
+	"os/user"
+	"runtime"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	defaultUnixShell = "/bin/sh"
+
+	pwshExe       = "pwsh.exe" // #nosec G101 - This is not a credential, just executable name
+	powershellExe = "powershell.exe"
+)
+
+// GetUserShell returns the appropriate shell for the given user ID.
+// Handles all platform-specific logic and fallbacks consistently.
+func GetUserShell(userID string) string {
+	switch runtime.GOOS {
+	case "windows":
+		return getWindowsUserShell()
+	default:
+		return getUnixUserShell(userID)
+	}
+}
+
+// getWindowsUserShell returns the best shell for Windows users.
+// We intentionally do not support cmd.exe or COMSPEC fallbacks to avoid command injection
+// vulnerabilities that arise from cmd.exe's complex command line parsing and special characters.
+// PowerShell provides safer argument handling and is available on all modern Windows systems.
+// Order: pwsh.exe -> powershell.exe
+func getWindowsUserShell() string {
+	if path, err := exec.LookPath(pwshExe); err == nil {
+		return path
+	}
+	if path, err := exec.LookPath(powershellExe); err == nil {
+		return path
+	}
+
+	return `C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`
+}
+
+// getUnixUserShell returns the shell for Unix-like systems.
+// Tries /etc/passwd first (fast, no subprocess), falls back to getent for NSS users.
+func getUnixUserShell(userID string) string {
+	if shell := getShellFromPasswd(userID); shell != "" {
+		return shell
+	}
+
+	if shell := GetShellFromGetent(userID); shell != "" {
+		return shell
+	}
+
+	if shell := os.Getenv("SHELL"); shell != "" {
+		return shell
+	}
+
+	return defaultUnixShell
+}
+
+// getShellFromPasswd reads the shell from /etc/passwd for the given user ID.
+func getShellFromPasswd(userID string) string {
+	file, err := os.Open("/etc/passwd")
+	if err != nil {
+		return ""
+	}
+	defer func() {
+		if err := file.Close(); err != nil {
+			log.Warnf("close /etc/passwd file: %v", err)
+		}
+	}()
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		fields := strings.Split(line, ":")
+		if len(fields) < 7 {
+			continue
+		}
+
+		// field 2 is UID
+		if fields[2] == userID {
+			shell := strings.TrimSpace(fields[6])
+			return shell
+		}
+	}
+
+	if err := scanner.Err(); err != nil {
+		log.Warnf("error reading /etc/passwd: %v", err)
+	}
+
+	return ""
+}
+
+// PrepareUserEnv prepares environment variables for user execution.
+func PrepareUserEnv(user *user.User, shell string) []string {
+	pathValue := "/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games"
+	if runtime.GOOS == "windows" {
+		pathValue = `C:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0`
+	}
+
+	return []string{
+		fmt.Sprint("SHELL=" + shell),
+		fmt.Sprint("USER=" + user.Username),
+		fmt.Sprint("LOGNAME=" + user.Username),
+		fmt.Sprint("HOME=" + user.HomeDir),
+		"PATH=" + pathValue,
+	}
+}
+
+// AcceptEnv checks if an environment variable from an SSH client should be accepted.
+// This is a whitelist of variables that SSH clients can send to the server.
+func AcceptEnv(envVar string) bool {
+	varName := envVar
+	if idx := strings.Index(envVar, "="); idx != -1 {
+		varName = envVar[:idx]
+	}
+
+	exactMatches := []string{
+		"LANG",
+		"LANGUAGE",
+		"TERM",
+		"COLORTERM",
+		"EDITOR",
+		"VISUAL",
+		"PAGER",
+		"LESS",
+		"LESSCHARSET",
+		"TZ",
+	}
+
+	prefixMatches := []string{
+		"LC_",
+	}
+
+	for _, exact := range exactMatches {
+		if varName == exact {
+			return true
+		}
+	}
+
+	for _, prefix := range prefixMatches {
+		if strings.HasPrefix(varName, prefix) {
+			return true
+		}
+	}
+
+	return false
+}