Documentation
¶
Overview ¶
Package server implements port forwarding for the SSH server.
Security note: Port forwarding runs in the main server process without privilege separation. The attack surface is primarily io.Copy through well-tested standard library code, making it lower risk than shell execution which uses privilege-separated child processes. We enforce user-level port restrictions: non-privileged users cannot bind to ports < 1024.
Index ¶
- Constants
- Variables
- func StartTestServer(t *testing.T, server *Server) string
- type Config
- type ExecutorConfig
- type JWTConfig
- type PrivilegeCheckRequest
- type PrivilegeCheckResult
- type PrivilegeDropper
- func (pd *PrivilegeDropper) CreateExecutorCommand(ctx context.Context, config ExecutorConfig) (*exec.Cmd, error)
- func (pd *PrivilegeDropper) DropPrivileges(targetUID, targetGID uint32, supplementaryGroups []uint32) error
- func (pd *PrivilegeDropper) ExecuteWithPrivilegeDrop(ctx context.Context, config ExecutorConfig)
- type PrivilegeDropperOption
- type PrivilegedUserError
- type Server
- func (s *Server) AddListener(ctx context.Context, addr netip.AddrPort) error
- func (s *Server) Addr() net.Addr
- func (s *Server) AuthConfig() *sshauth.Config
- func (s *Server) CheckPrivileges(req PrivilegeCheckRequest) PrivilegeCheckResult
- func (s *Server) GetStatus() (enabled bool, sessions []SessionInfo)
- func (s *Server) JWTConfig() *JWTConfig
- func (s *Server) SetAllowLocalPortForwarding(allow bool)
- func (s *Server) SetAllowRemotePortForwarding(allow bool)
- func (s *Server) SetAllowRootLogin(allow bool)
- func (s *Server) SetAllowSFTP(allow bool)
- func (s *Server) SetNetstackNet(net *wgbackend.NetstackNet)
- func (s *Server) SetNetworkValidation(addr wgaddr.Address)
- func (s *Server) Start(ctx context.Context, addr netip.AddrPort) error
- func (s *Server) Stop() error
- func (s *Server) UpdateSSHAuth(config *sshauth.Config)
- type SessionInfo
- type UserNotFoundError
Constants ¶
const ( ExitCodeSuccess = 0 ExitCodePrivilegeDropFail = 10 ExitCodeShellExecFail = 11 ExitCodeValidationFail = 12 )
Exit codes for executor process communication
const ( // FeatureSSHLogin represents SSH login operations for privilege checking FeatureSSHLogin = "SSH login" // FeatureSFTP represents SFTP operations for privilege checking FeatureSFTP = "SFTP" )
const ( // DefaultJWTMaxTokenAge is the default maximum age for JWT tokens accepted by the SSH server. // Set to 10 minutes to accommodate identity providers like Azure Entra ID // that backdate the iat claim by up to 5 minutes. DefaultJWTMaxTokenAge = 10 * 60 )
const DefaultSSHPort = 22
DefaultSSHPort is the default SSH port of the NetBird's embedded SSH server
const InternalSSHPort = 22022
InternalSSHPort is the port SSH server listens on and is redirected to
Variables ¶
var ( ErrPrivilegedUserDisabled = errors.New(msgPrivilegedUserDisabled) ErrUserNotFound = errors.New("user not found") )
var ( ErrPrivilegeRequired = errors.New("SeAssignPrimaryTokenPrivilege required for user switching - NetBird must run with elevated privileges") ErrPrivilegedUserSwitch = errors.New("cannot switch to privileged user - current user lacks required privileges") )
Functions ¶
Types ¶
type Config ¶
type Config struct {
// JWT authentication configuration. If nil, JWT authentication is disabled
JWT *JWTConfig
// HostKey is the SSH server host key in PEM format
HostKeyPEM []byte
// Auth is the fine-grained authorization to open with. Nil starts with an
// empty authorizer, which authorizes nobody until UpdateSSHAuth is called.
// Setting it here rather than afterwards means the server never accepts a
// login before it knows who is allowed.
Auth *sshauth.Config
}
Config contains all SSH server configuration options
type ExecutorConfig ¶
type ExecutorConfig struct {
UID uint32
GID uint32
Groups []uint32
WorkingDir string
Shell string
Command string
PTY bool
// NoLoginShell starts the shell as a plain shell instead of a login shell, so the
// user's profile output stays out of a protocol spoken over stdout.
NoLoginShell bool
}
ExecutorConfig holds configuration for the executor process
type PrivilegeCheckRequest ¶
type PrivilegeCheckRequest struct {
// Username being requested (empty = current user)
RequestedUsername string
FeatureSupportsUserSwitch bool // Does this feature/operation support user switching?
FeatureName string
}
PrivilegeCheckRequest represents a privilege check request
type PrivilegeCheckResult ¶
type PrivilegeCheckResult struct {
// Allowed indicates whether the privilege check passed
Allowed bool
// User is the effective user to use for the operation (nil if not allowed)
User *user.User
// Error contains the reason for denial (nil if allowed)
Error error
// UsedFallback indicates we fell back to current user instead of requested user.
// This happens on Unix when running as an unprivileged user (e.g., in containers)
// where there's no point in user switching since we lack privileges anyway.
// When true, all privilege checks have already been performed and no additional
// privilege dropping or root checks are needed - the current user is the target.
UsedFallback bool
// RequiresUserSwitching indicates whether user switching will actually occur
// (false for fallback cases where no actual switching happens)
RequiresUserSwitching bool
}
PrivilegeCheckResult represents the result of a privilege check
type PrivilegeDropper ¶
type PrivilegeDropper struct {
// contains filtered or unexported fields
}
PrivilegeDropper handles secure privilege dropping in child processes
func NewPrivilegeDropper ¶
func NewPrivilegeDropper(opts ...PrivilegeDropperOption) *PrivilegeDropper
NewPrivilegeDropper creates a new privilege dropper
func (*PrivilegeDropper) CreateExecutorCommand ¶
func (pd *PrivilegeDropper) CreateExecutorCommand(ctx context.Context, config ExecutorConfig) (*exec.Cmd, error)
CreateExecutorCommand creates a command that spawns netbird ssh exec for privilege dropping
func (*PrivilegeDropper) DropPrivileges ¶
func (pd *PrivilegeDropper) DropPrivileges(targetUID, targetGID uint32, supplementaryGroups []uint32) error
DropPrivileges performs privilege dropping with thread locking for security
func (*PrivilegeDropper) ExecuteWithPrivilegeDrop ¶
func (pd *PrivilegeDropper) ExecuteWithPrivilegeDrop(ctx context.Context, config ExecutorConfig)
ExecuteWithPrivilegeDrop executes a command with privilege dropping, using exit codes to signal specific failures
type PrivilegeDropperOption ¶ added in v0.64.2
type PrivilegeDropperOption func(*PrivilegeDropper)
PrivilegeDropperOption is a functional option for configuring PrivilegeDropper
func WithLogger ¶ added in v0.64.2
func WithLogger(logger *log.Entry) PrivilegeDropperOption
WithLogger sets the logger for the PrivilegeDropper
type PrivilegedUserError ¶
type PrivilegedUserError struct {
Username string
}
PrivilegedUserError represents an error when privileged user login is disabled
func (*PrivilegedUserError) Error ¶
func (e *PrivilegedUserError) Error() string
func (*PrivilegedUserError) Is ¶
func (e *PrivilegedUserError) Is(target error) bool
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func New ¶
New creates an SSH server instance with the provided host key and optional JWT configuration If config.JWT is nil, JWT authentication is disabled.
func (*Server) AddListener ¶ added in v0.71.0
AddListener starts serving SSH on an additional address (e.g. IPv6). Must be called after Start.
func (*Server) Addr ¶ added in v0.62.0
Addr returns the address the SSH server is listening on, or nil if the server is not running
func (*Server) AuthConfig ¶ added in v0.78.0
AuthConfig returns the fine-grained authorization currently in force, or nil when the server has no authorizer.
func (*Server) CheckPrivileges ¶
func (s *Server) CheckPrivileges(req PrivilegeCheckRequest) PrivilegeCheckResult
CheckPrivileges performs comprehensive privilege checking for all SSH features. This is the single source of truth for privilege decisions across the SSH server.
func (*Server) GetStatus ¶
func (s *Server) GetStatus() (enabled bool, sessions []SessionInfo)
GetStatus returns the current status of the SSH server and active sessions.
func (*Server) JWTConfig ¶ added in v0.78.0
JWTConfig returns the JWT authentication this server was built with, or nil when JWT authentication is disabled.
func (*Server) SetAllowLocalPortForwarding ¶
SetAllowLocalPortForwarding configures local port forwarding
func (*Server) SetAllowRemotePortForwarding ¶
SetAllowRemotePortForwarding configures remote port forwarding
func (*Server) SetAllowRootLogin ¶
SetAllowRootLogin configures root login access
func (*Server) SetAllowSFTP ¶
SetAllowSFTP enables or disables SFTP support
func (*Server) SetNetstackNet ¶
func (s *Server) SetNetstackNet(net *wgbackend.NetstackNet)
SetNetstackNet sets the netstack network for userspace networking
func (*Server) SetNetworkValidation ¶
SetNetworkValidation configures network-based connection filtering
func (*Server) Stop ¶
Stop closes the SSH server, including connections still authenticating and remote forwarding listeners, and clears session and connection state. It does nothing if already stopped and always returns nil, even if closing fails.
func (*Server) UpdateSSHAuth ¶ added in v0.61.0
UpdateSSHAuth updates the SSH fine-grained access control configuration This should be called when network map updates include new SSH auth configuration Connections of users the new configuration no longer authorizes are closed.
type SessionInfo ¶
type SessionInfo struct {
Username string
RemoteAddress string
Command string
JWTUsername string
PortForwards []string
}
SessionInfo contains information about an active SSH session
type UserNotFoundError ¶
UserNotFoundError represents an error when a user cannot be found
func (*UserNotFoundError) Error ¶
func (e *UserNotFoundError) Error() string
func (*UserNotFoundError) Is ¶
func (e *UserNotFoundError) Is(target error) bool
func (*UserNotFoundError) Unwrap ¶
func (e *UserNotFoundError) Unwrap() error