Add SSH agent forwarding support to guest SSH server

Enable the SSH server to accept auth-agent-req@openssh.com requests
and create per-session Unix domain agent sockets. When a guest process
connects to the socket, the server opens an auth-agent@openssh.com
channel back to the client and pipes bidirectionally.

Controlled via WithSSHAgentForwarding boot option (default: off).
Includes concurrency limits (max 8 agent connections), explicit socket
permissions (0700/0600), and proper goroutine lifecycle tracking.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JAORMX

guest/boot/boot.go

@@ -103,16 +103,17 @@ func Run(logger *slog.Logger, opts ...Option) (shutdown func(), err error) {
 
 	// 9. Start SSH server.
 	sshdCfg := sshd.Config{
-		Port:           cfg.sshPort,
-		AuthorizedKeys: authorizedKeys,
-		Env:            envVars,
-		DefaultUID:     cfg.userUID,
-		DefaultGID:     cfg.userGID,
-		DefaultUser:    cfg.userName,
-		DefaultHome:    cfg.userHome,
-		DefaultShell:   cfg.userShell,
-		DefaultWorkDir: cfg.workspaceMountPoint,
-		Logger:         logger,
+		Port:            cfg.sshPort,
+		AuthorizedKeys:  authorizedKeys,
+		Env:             envVars,
+		DefaultUID:      cfg.userUID,
+		DefaultGID:      cfg.userGID,
+		DefaultUser:     cfg.userName,
+		DefaultHome:     cfg.userHome,
+		DefaultShell:    cfg.userShell,
+		DefaultWorkDir:  cfg.workspaceMountPoint,
+		AgentForwarding: cfg.sshAgentForwarding,
+		Logger:          logger,
 	}
 	srv, err := sshd.New(sshdCfg)
 	if err != nil {

guest/boot/options.go

@@ -30,6 +30,7 @@ type config struct {
 	userUID             uint32
 	userGID             uint32
 	lockdownRoot        bool
+	sshAgentForwarding  bool
 }
 
 func defaultConfig() *config {
@@ -96,3 +97,10 @@ func WithUser(name, home, shell string, uid, gid uint32) Option {
 func WithLockdownRoot(enabled bool) Option {
 	return optionFunc(func(c *config) { c.lockdownRoot = enabled })
 }
+
+// WithSSHAgentForwarding controls whether the SSH server supports
+// agent forwarding. When enabled and the client requests it, the
+// server creates a Unix socket and sets SSH_AUTH_SOCK for the session.
+func WithSSHAgentForwarding(enabled bool) Option {
+	return optionFunc(func(c *config) { c.sshAgentForwarding = enabled })
+}

guest/sshd/server.go

@@ -61,18 +61,25 @@ type Config struct {
 	// empty or the directory does not exist, DefaultHome is used instead.
 	DefaultWorkDir string
 
+	// AgentForwarding enables SSH agent forwarding support. When true,
+	// the server accepts auth-agent-req@openssh.com requests and creates
+	// per-session agent sockets.
+	AgentForwarding bool
+
 	// Logger is the structured logger. If nil, slog.Default() is used.
 	Logger *slog.Logger
 }
 
 // Server is an embedded SSH server designed to run inside a guest VM.
 type Server struct {
-	cfg      Config
-	sshCfg   *ssh.ServerConfig
-	listener net.Listener
-	wg       sync.WaitGroup
-	quit     chan struct{}
-	logger   *slog.Logger
+	cfg        Config
+	sshCfg     *ssh.ServerConfig
+	listener   net.Listener
+	wg         sync.WaitGroup
+	quit       chan struct{}
+	logger     *slog.Logger
+	agentFwdMu sync.Mutex
+	agentFwd   map[*ssh.ServerConn]bool
 }
 
 // New creates a new Server with an ephemeral ECDSA P-256 host key. It
@@ -119,10 +126,11 @@ func New(cfg Config) (*Server, error) {
 	sshCfg.AddHostKey(signer)
 
 	return &Server{
-		cfg:    cfg,
-		sshCfg: sshCfg,
-		quit:   make(chan struct{}),
-		logger: logger,
+		cfg:      cfg,
+		sshCfg:   sshCfg,
+		quit:     make(chan struct{}),
+		logger:   logger,
+		agentFwd: make(map[*ssh.ServerConn]bool),
 	}, nil
 }
 
@@ -206,6 +214,7 @@ func (s *Server) handleConnection(netConn net.Conn) {
 		return
 	}
 	defer func() { _ = srvConn.Close() }()
+	defer s.setAgentForwarding(srvConn, false)
 
 	// Clear the deadline after a successful handshake.
 	if err := netConn.SetDeadline(time.Time{}); err != nil {
@@ -218,8 +227,8 @@ func (s *Server) handleConnection(netConn net.Conn) {
 		"remote", srvConn.RemoteAddr(),
 	)
 
-	// Discard all global requests (keepalive, etc.).
-	go ssh.DiscardRequests(reqs)
+	// Handle global requests (agent forwarding, keepalive, etc.).
+	go s.handleGlobalRequests(reqs, srvConn)
 
 	channelCount := 0
 	for newCh := range chans {
@@ -249,7 +258,58 @@ func (s *Server) handleConnection(netConn net.Conn) {
 		s.wg.Add(1)
 		go func() {
 			defer s.wg.Done()
-			s.handleSession(ch, requests)
+			s.handleSession(ch, requests, srvConn)
 		}()
 	}
 }
+
+// handleGlobalRequests processes connection-level SSH requests.
+// It handles agent forwarding requests when enabled and discards
+// all other global requests.
+func (s *Server) handleGlobalRequests(reqs <-chan *ssh.Request, conn *ssh.ServerConn) {
+	for req := range reqs {
+		switch req.Type {
+		case "auth-agent-req@openssh.com":
+			if s.cfg.AgentForwarding {
+				s.setAgentForwarding(conn, true)
+				s.logger.Info("agent forwarding enabled",
+					"remote", conn.RemoteAddr(),
+				)
+				if req.WantReply {
+					_ = req.Reply(true, nil)
+				}
+			} else {
+				s.logger.Debug("agent forwarding rejected (disabled)",
+					"remote", conn.RemoteAddr(),
+				)
+				if req.WantReply {
+					_ = req.Reply(false, nil)
+				}
+			}
+		default:
+			if req.WantReply {
+				_ = req.Reply(false, nil)
+			}
+		}
+	}
+}
+
+// setAgentForwarding records or clears the agent-forwarding state for
+// the given connection.
+func (s *Server) setAgentForwarding(conn *ssh.ServerConn, enabled bool) {
+	s.agentFwdMu.Lock()
+	defer s.agentFwdMu.Unlock()
+	if enabled {
+		s.agentFwd[conn] = true
+	} else {
+		delete(s.agentFwd, conn)
+	}
+}
+
+// isAgentForwarding reports whether agent forwarding has been enabled
+// for the given connection.
+func (s *Server) isAgentForwarding(conn *ssh.ServerConn) bool {
+	s.agentFwdMu.Lock()
+	defer s.agentFwdMu.Unlock()
+	return s.agentFwd[conn]
+}

guest/sshd/server_test.go

@@ -307,3 +307,123 @@ func TestDefaultWorkDirFallback(t *testing.T) {
 
 	assert.Equal(t, expected, strings.TrimSpace(string(output)))
 }
+
+func TestAgentForwardingDisabled(t *testing.T) {
+	t.Parallel()
+
+	signer, pubKey := generateTestKeyPair(t)
+	_, addr := startTestServerWithConfig(t, Config{
+		Port:            0,
+		AuthorizedKeys:  []ssh.PublicKey{pubKey},
+		Env:             []string{"PATH=/usr/bin:/bin"},
+		DefaultUID:      uint32(os.Getuid()),
+		DefaultGID:      uint32(os.Getgid()),
+		DefaultUser:     "testuser",
+		DefaultHome:     os.TempDir(),
+		DefaultShell:    "/bin/sh",
+		AgentForwarding: false,
+		Logger:          slog.Default(),
+	})
+
+	client := dialSSH(t, addr, signer)
+
+	// Request agent forwarding — should be rejected.
+	ok, _, err := client.SendRequest("auth-agent-req@openssh.com", true, nil)
+	require.NoError(t, err)
+	assert.False(t, ok, "agent forwarding should be rejected when disabled")
+}
+
+func TestAgentForwardingEnabled(t *testing.T) {
+	t.Parallel()
+
+	signer, pubKey := generateTestKeyPair(t)
+	_, addr := startTestServerWithConfig(t, Config{
+		Port:            0,
+		AuthorizedKeys:  []ssh.PublicKey{pubKey},
+		Env:             []string{"PATH=/usr/bin:/bin"},
+		DefaultUID:      uint32(os.Getuid()),
+		DefaultGID:      uint32(os.Getgid()),
+		DefaultUser:     "testuser",
+		DefaultHome:     os.TempDir(),
+		DefaultShell:    "/bin/sh",
+		AgentForwarding: true,
+		Logger:          slog.Default(),
+	})
+
+	client := dialSSH(t, addr, signer)
+
+	// Request agent forwarding — should be accepted.
+	ok, _, err := client.SendRequest("auth-agent-req@openssh.com", true, nil)
+	require.NoError(t, err)
+	assert.True(t, ok, "agent forwarding should be accepted when enabled")
+}
+
+func TestAgentSocketCreated(t *testing.T) {
+	t.Parallel()
+
+	signer, pubKey := generateTestKeyPair(t)
+	_, addr := startTestServerWithConfig(t, Config{
+		Port:            0,
+		AuthorizedKeys:  []ssh.PublicKey{pubKey},
+		Env:             []string{"PATH=/usr/bin:/bin"},
+		DefaultUID:      uint32(os.Getuid()),
+		DefaultGID:      uint32(os.Getgid()),
+		DefaultUser:     "testuser",
+		DefaultHome:     os.TempDir(),
+		DefaultShell:    "/bin/sh",
+		AgentForwarding: true,
+		Logger:          slog.Default(),
+	})
+
+	client := dialSSH(t, addr, signer)
+
+	// Request agent forwarding.
+	ok, _, err := client.SendRequest("auth-agent-req@openssh.com", true, nil)
+	require.NoError(t, err)
+	require.True(t, ok)
+
+	// Run a command that checks if SSH_AUTH_SOCK is set.
+	session, err := client.NewSession()
+	require.NoError(t, err)
+	defer func() { _ = session.Close() }()
+
+	output, err := session.CombinedOutput("echo $SSH_AUTH_SOCK")
+	require.NoError(t, err)
+
+	sockPath := strings.TrimSpace(string(output))
+	assert.NotEmpty(t, sockPath, "SSH_AUTH_SOCK should be set when agent forwarding is enabled")
+	assert.Contains(t, sockPath, "/tmp/ssh-", "agent socket should be in /tmp/ssh-*")
+}
+
+func TestNoSocketWithoutForwardingRequest(t *testing.T) {
+	t.Parallel()
+
+	signer, pubKey := generateTestKeyPair(t)
+	_, addr := startTestServerWithConfig(t, Config{
+		Port:            0,
+		AuthorizedKeys:  []ssh.PublicKey{pubKey},
+		Env:             []string{"PATH=/usr/bin:/bin"},
+		DefaultUID:      uint32(os.Getuid()),
+		DefaultGID:      uint32(os.Getgid()),
+		DefaultUser:     "testuser",
+		DefaultHome:     os.TempDir(),
+		DefaultShell:    "/bin/sh",
+		AgentForwarding: true,
+		Logger:          slog.Default(),
+	})
+
+	client := dialSSH(t, addr, signer)
+
+	// Do NOT request agent forwarding.
+
+	// Run a command that checks if SSH_AUTH_SOCK is set.
+	session, err := client.NewSession()
+	require.NoError(t, err)
+	defer func() { _ = session.Close() }()
+
+	output, err := session.CombinedOutput("echo ${SSH_AUTH_SOCK:-unset}")
+	require.NoError(t, err)
+
+	result := strings.TrimSpace(string(output))
+	assert.Equal(t, "unset", result, "SSH_AUTH_SOCK should not be set without forwarding request")
+}