rce

README

RCE Agent

rce-agent is a gRPC-based Remote Command Execution (RCE) client and server. The server (or "agent") runs on a remote host and executes a whitelist of shell commands specified in a file. The client calls the agent to execute whitelist commands. TLS is used to secure and authenticate both client and server.

rce-agent replaces SSH and other methods of remote code execution. There are no passwords—only TLS certificates—and commands are limited to a whitelist. This eliminates the need for SSH keys, passwords, or forwarding.

This package is meant to be integrated into your code. The rce.Client and rce.Server objects do all the heavy lifting so your client and agent code can focus on their domain-specific logic. See example/ for example code.

RCE Agent is also meant to be used with your private certificate authority (CA) for TLS-encrypted communication and mutual authentication of client and agent. (Setting up a private CA is beyond the scope of this project, but we highly suggest you use one!) Normally, only the client verifies the server's TLS certificate (cert). For additional security, your code should use rce.TLSFiles to create Go tls.Config which makes the server (agent) verify the client's cert, too.

Documentation

Overview

Package rce provides a gRPC-based Remote Code Execution client and server. The server (or "agent") runs on a remote host and executes a whitelist of shell commands specified in a config file. The client calls the server to execute whitelist commands. Commands from different clients run concurrently; there are no safeguards against conflicting or incompatible commands.

Index

• Variables
• type Client
  • func NewClient(tlsConfig *tls.Config) Client
• type Server
  • func NewServer(laddr string, tlsConfig *tls.Config, whitelist cmd.Runnable) Server
  • func NewServerWithConfig(cfg ServerConfig) Server
• type ServerConfig
• type TLSFiles
  • func (f TLSFiles) TLSConfig() (*tls.Config, error)

Variables

var (
	// ConnectTimeout describes the total timeout for establishing a client
	// connection to the rceagent server.
	ConnectTimeout = time.Duration(10) * time.Second

	// ConnectBackoffMaxDelay configures the dialer to use the
	// provided maximum delay when backing off after
	// failed connection attempts.
	ConnectBackoffMaxDelay = time.Duration(2) * time.Second

	// KeepaliveTime is the interval at which the client sends keepalive
	// probes to the server.
	KeepaliveTime = time.Duration(30) * time.Second

	// KeepaliveTimeout is the amount of time the client waits to receive
	// a response from the server after a keepalive probe.
	KeepaliveTimeout = time.Duration(20) * time.Second
)

var (
	// ErrInvalidServerConfigAllowAnyCommand is returned by Server.StartServer() when
	// ServerConfig.AllowAnyCommand is true but ServerConfig.AllowedCommands is non-nil.
	ErrInvalidServerConfigAllowAnyCommand = errors.New("invalid ServerConfig: AllowAnyCommand is true but AllowedCommands is non-nil")

	// ErrInvalidServerConfigDisableSecurity is returned by Server.StartServer()
	// when ServerConfig.AllowAnyCommand is true and ServerConfig.TLS is nil but
	// ServerConfig.DisableSecurity is false.
	ErrInvalidServerConfigDisableSecurity = errors.New("invalid ServerConfig: AllowAnyCommand enabled but TLS is nil")

	// ErrCommandNotAllowed is safeguard error returned by the internal gRPC server when
	// ServerConfig.AllowedCommands is nil and ServerConfig.AllowAnyCommand is false.
	// This should not happen because these values are validated in Server.StartServer()
	// before starting the internal gRPC server. If this error occurs, there is a bug
	// in ServerConfig validation code.
	ErrCommandNotAllowed = errors.New("command not allowed")
)

Types

type Client

type Client interface {
	// Connect to a remote agent.
	Open(host, port string) error

	// Close connection to a remote agent.
	Close() error

	// Return hostname and port of remote agent, if connected.
	AgentAddr() (string, string)

	// Start a command on the remote agent. Must be connected first by calling
	// Connect. This call is non-blocking. It returns the ID of the command or
	// an error.
	Start(cmdName string, args []string) (id string, err error)

	// Wait for a command on the remote agent. This call blocks until the command
	// completes. It returns the final statue of the command or an error.
	Wait(id string) (*pb.Status, error)

	// Get the status of a running command. This is safe to call by multiple
	// goroutines. ErrNotFound is returned if Wait or Stop has already been
	// called.
	GetStatus(id string) (*pb.Status, error)

	// Stop a running command. ErrNotFound is returne if Wait or Stop has already
	// been called.
	Stop(id string) error

	// Return a list of all running command IDs.
	Running() ([]string, error)
}

A Client calls a remote agent (server) to execute commands.

func NewClient

func NewClient(tlsConfig *tls.Config) Client

NewClient makes a new Client.

type Server

type Server interface {
	// Start the gRPC server, non-blocking.
	StartServer() error

	// Stop the gRPC server gracefully.
	StopServer() error

	pb.RCEAgentServer
}

A Server executes a whitelist of commands when called by clients.

func NewServer

func NewServer(laddr string, tlsConfig *tls.Config, whitelist cmd.Runnable) Server

NewServer makes a new Server that listens on laddr and runs the whitelist of commands. If tlsConfig is nil, the sever is insecure.

func NewServerWithConfig

func NewServerWithConfig(cfg ServerConfig) Server

type ServerConfig

type ServerConfig struct {

	// Addr is the required host:post listen address.
	Addr string

	// AllowedCommands is the list of commands the server is allowed to run.
	// By default, no commands are allowed; commands must be explicitly allowed.
	AllowedCommands cmd.Runnable

	// AllowAnyCommand allows any commands if AllowedCommands is nil.
	// This is not recommended. If true, TLS must be specified (non-nil);
	// or, to enable AllowAnyCommand without TLS, DisableSecurity must be true.
	AllowAnyCommand bool

	// DisableSecurity allows AllowAnyCommand without TLS: an insecure server that
	// can execute any command from any client.
	//
	// This option should not be used.
	DisableSecurity bool

	// TLS specifies the TLS configuration for secure and verified communication.
	// Use TLSFiles.TLSConfig() to load TLS files and configure for server and
	// client verification.
	TLS *tls.Config
}

ServerConfig configures a Server.

type TLSFiles

type TLSFiles struct {
	CACert string
	Cert   string
	Key    string
}

TLSFiles represents the TLS files necessary to create a tls.Config.

func (TLSFiles) TLSConfig

func (f TLSFiles) TLSConfig() (*tls.Config, error)

TLSConfig returns a new tls.Config.