fix(agent): fail native sessions loudly when setgroups is denied

In native mode the agent switches credentials via SysProcAttr.Credential
when running as root, which makes the Go runtime call setgroups() during
cmd.Start() — even for an empty group list. In an unprivileged user
namespace /proc/self/setgroups is "deny", so setgroups fails with EPERM
and every native SSH session dies right after auth with a cryptic error.

Detect the denied policy up front (euid 0 AND /proc/self/setgroups ==
"deny") via a new command.CheckCredentialSwitch seam and refuse the
session with a clear error and Exit(1) before launching the shell, rather
than dropping supplementary groups silently. Docker mode is unaffected
(it switches privileges via setpriv/nsenter) and gets a no-op.

Also harden Heredoc against two latent nil-deref panics on a cmd.Start()
failure (nil ProcessState, and the kill-goroutine racing on a nil
Process), and add a non-prescriptive PTY-allocation hint to the Shell and
Exec logs on ENOTTY.

Author: otavio

agent/server/modes/host/command/command_docker.go

@@ -29,6 +29,12 @@ func nsenterArgs(present map[string]string) []string {
 	return args
 }
 
+// CheckCredentialSwitch is a no-op in Docker mode: the agent relies on
+// nsenter+setpriv for credential switching, so this check is not applicable.
+func CheckCredentialSwitch() error {
+	return nil
+}
+
 func NewCmd(u *osauth.User, shell, term, host string, envs []string, command ...string) *exec.Cmd {
 	groups, err := osauth.ListGroups(u.Username)
 	if err != nil {

agent/server/modes/host/command/command_docker_compile_test.go

@@ -0,0 +1,24 @@
+//go:build docker
+// +build docker
+
+package command
+
+import "testing"
+
+// Compile-time assertion: CheckCredentialSwitch is exported and has the expected
+// signature (func() error) under the docker build tag.  This mirrors the
+// identical assertion in command_native_test.go for the !docker tag so that
+// neither tag set can silently break the build.
+var _ func() error = CheckCredentialSwitch
+
+// TestCheckCredentialSwitchCompiles is a named test that anchors the
+// compile-time assertion above so it shows up in the test run output.
+// The assertion is evaluated at compile time; the test body itself is a
+// simple pass-through that confirms the symbol is reachable at runtime too.
+func TestCheckCredentialSwitchCompiles(t *testing.T) {
+	// Calling the function ensures the linker includes the symbol and that
+	// it actually returns nil in docker mode (documented no-op).
+	if err := CheckCredentialSwitch(); err != nil {
+		t.Errorf("CheckCredentialSwitch() returned unexpected error under -tags docker: %v", err)
+	}
+}

agent/server/modes/host/command/command_native.go

@@ -4,14 +4,68 @@
 package command
 
 import (
+	"errors"
 	"os"
 	"os/exec"
+	"strings"
 	"syscall"
 
 	"github.com/shellhub-io/shellhub/agent/pkg/osauth"
 	log "github.com/sirupsen/logrus"
 )
 
+// geteuidFn is a seam for os.Geteuid used in setgroupsDenied and NewCmd.
+// Tests can replace it to simulate running as root or non-root.
+var geteuidFn = os.Geteuid
+
+// readSetgroupsPolicyFn is a seam for reading /proc/self/setgroups.
+// Tests can replace it to control the kernel policy value without filesystem access.
+var readSetgroupsPolicyFn = func() ([]byte, error) {
+	return os.ReadFile("/proc/self/setgroups")
+}
+
+// setgroupsDenied reports whether the kernel has denied setgroups(2) for this
+// process by checking /proc/self/setgroups.
+//
+// Return values:
+//   - true:  the policy file trims to "deny".
+//   - false: the file does not exist (kernel too old or not in a user-ns); silent.
+//   - false: any other read error; a warning is emitted via the logger.
+func setgroupsDenied() bool {
+	data, err := readSetgroupsPolicyFn()
+	if err != nil {
+		if !errors.Is(err, os.ErrNotExist) {
+			log.WithError(err).Warn("failed to read /proc/self/setgroups; assuming setgroups is allowed")
+		}
+
+		return false
+	}
+
+	return strings.TrimSpace(string(data)) == "deny"
+}
+
+// CheckCredentialSwitch reports whether the process can switch credentials via
+// setgroups(2).  It is a pre-flight check that must be called before attempting
+// to execute a command as a different user.
+//
+// Short-circuit: when the effective UID is not root (euid != 0), credential
+// switching is a no-op and the check always succeeds (nil).
+//
+// When euid == 0, the kernel may still forbid setgroups inside an unprivileged
+// user namespace (Linux ≥ 3.19).  In that case the function returns a sentinel
+// error whose message contains "setgroups denied in unprivileged user namespace".
+func CheckCredentialSwitch() error {
+	if geteuidFn() != 0 {
+		return nil
+	}
+
+	if setgroupsDenied() {
+		return errors.New("setgroups denied in unprivileged user namespace")
+	}
+
+	return nil
+}
+
 func NewCmd(u *osauth.User, shell, term, host string, envs []string, command ...string) *exec.Cmd {
 	groups, err := osauth.ListGroups(u.Username)
 	if err != nil {
@@ -44,7 +98,7 @@ func NewCmd(u *osauth.User, shell, term, host string, envs []string, command ...
 		cmd.Dir = u.HomeDir
 	}
 
-	if os.Geteuid() == 0 {
+	if geteuidFn() == 0 {
 		cmd.SysProcAttr = &syscall.SysProcAttr{}
 		cmd.SysProcAttr.Credential = &syscall.Credential{Uid: u.UID, Gid: u.GID, Groups: groups}
 	}

agent/server/modes/host/command/command_native_test.go

@@ -0,0 +1,152 @@
+//go:build !docker
+// +build !docker
+
+package command
+
+import (
+	"errors"
+	"os"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// Compile-time assertion: CheckCredentialSwitch must be defined under the !docker tag.
+var _ = CheckCredentialSwitch
+
+// TestSetgroupsDenied verifies the setgroupsDenied helper across all documented
+// scenarios.  Tests do NOT call t.Parallel() because they mutate package-level
+// seam variables.
+//
+//nolint:paralleltest
+func TestSetgroupsDenied(t *testing.T) {
+	origGeteuidFn := geteuidFn
+	origReadSetgroupsPolicyFn := readSetgroupsPolicyFn
+
+	t.Cleanup(func() {
+		geteuidFn = origGeteuidFn
+		readSetgroupsPolicyFn = origReadSetgroupsPolicyFn
+	})
+
+	t.Run("'deny' returns true", func(t *testing.T) {
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return []byte("deny"), nil
+		}
+
+		assert.True(t, setgroupsDenied())
+	})
+
+	t.Run("'deny\\n' returns true", func(t *testing.T) {
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return []byte("deny\n"), nil
+		}
+
+		assert.True(t, setgroupsDenied())
+	})
+
+	t.Run("' deny \\n' returns true", func(t *testing.T) {
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return []byte(" deny \n"), nil
+		}
+
+		assert.True(t, setgroupsDenied())
+	})
+
+	t.Run("'allow' returns false", func(t *testing.T) {
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return []byte("allow"), nil
+		}
+
+		assert.False(t, setgroupsDenied())
+	})
+
+	t.Run("ErrNotExist returns false without warning", func(t *testing.T) {
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return nil, os.ErrNotExist
+		}
+
+		// No warning expected — just false.
+		assert.False(t, setgroupsDenied())
+	})
+
+	t.Run("other read error returns false with warning", func(t *testing.T) {
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return nil, errors.New("permission denied")
+		}
+
+		// Should return false (and emit a warning via log, but we do not
+		// capture log output — the return value is what matters here).
+		assert.False(t, setgroupsDenied())
+	})
+}
+
+// TestCheckCredentialSwitch verifies CheckCredentialSwitch across its four
+// documented scenarios.  Tests do NOT call t.Parallel() because they mutate
+// package-level seam variables.
+//
+//nolint:paralleltest
+func TestCheckCredentialSwitch(t *testing.T) {
+	origGeteuidFn := geteuidFn
+	origReadSetgroupsPolicyFn := readSetgroupsPolicyFn
+
+	t.Cleanup(func() {
+		geteuidFn = origGeteuidFn
+		readSetgroupsPolicyFn = origReadSetgroupsPolicyFn
+	})
+
+	t.Run("euid!=0 returns nil without reading setgroups policy", func(t *testing.T) {
+		var calls atomic.Int64
+
+		geteuidFn = func() int { return 1000 }
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			calls.Add(1)
+
+			return []byte("deny"), nil
+		}
+
+		err := CheckCredentialSwitch()
+
+		assert.NoError(t, err)
+		assert.Equal(t, int64(0), calls.Load(), "readSetgroupsPolicyFn must never be called when euid!=0")
+	})
+
+	t.Run("euid!=0 with deny policy still returns nil (stub never called)", func(t *testing.T) {
+		var calls atomic.Int64
+
+		geteuidFn = func() int { return 500 }
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			calls.Add(1)
+
+			return []byte("deny"), nil
+		}
+
+		err := CheckCredentialSwitch()
+
+		assert.NoError(t, err)
+		assert.Equal(t, int64(0), calls.Load(), "readSetgroupsPolicyFn must never be called when euid!=0")
+	})
+
+	t.Run("euid==0 and setgroups deny returns error containing 'setgroups denied in unprivileged user namespace'", func(t *testing.T) {
+		geteuidFn = func() int { return 0 }
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return []byte("deny"), nil
+		}
+
+		err := CheckCredentialSwitch()
+
+		assert.Error(t, err)
+		assert.ErrorContains(t, err, "setgroups denied in unprivileged user namespace")
+	})
+
+	t.Run("euid==0 and setgroups allow returns nil", func(t *testing.T) {
+		geteuidFn = func() int { return 0 }
+		readSetgroupsPolicyFn = func() ([]byte, error) {
+			return []byte("allow"), nil
+		}
+
+		err := CheckCredentialSwitch()
+
+		assert.NoError(t, err)
+	})
+}